scene-capability-engine 3.6.60 → 3.6.61

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.61] - 2026-03-20
+
+### Added
+- Added `sce project candidate inspect --root <path> --json` as the canonical single-root inspection contract for workspace-backed roots, local `.sce` candidates, ordinary directory candidates, and invalid roots.
+- Added `sce project onboarding import --root <path> --json` as the canonical root-based onboarding entry, reusing the ordered `register/attach/hydrate/activate/scaffold` step envelope instead of inventing a second import receipt.
+
+### Changed
+- MagicBall-facing multi-project docs, command reference, CLI examples, frontend mapping, and release-time project-contract audit now include `project candidate inspect` and `project onboarding import` alongside the existing portfolio/target/supervision contracts.
+- Root-based onboarding now suppresses internal adoption progress logs in `--json` mode so adapters receive clean machine-readable envelopes.
+
 ## [3.6.60] - 2026-03-19
 
 ### Changed

package/README.md

@@ -174,7 +174,7 @@ MagicBall-specific integration surfaces now also include:
 - `sce app registry status|configure|sync*`
 - `sce app runtime show|releases|install|activate|uninstall`
 - `sce app engineering preview|ownership|open|import|show|attach|hydrate|scaffold|activate`
-- `sce project portfolio show|target resolve|supervision show`
+- `sce project portfolio show|candidate inspect|onboarding import|target resolve|supervision show`
 - `sce mode application|ontology|engineering home`
 - `sce pm requirement|tracking|planning|change|issue ... --json`
 - `sce ontology er|br|dl ... --json`
@@ -230,5 +230,5 @@ MIT. See [LICENSE](LICENSE).
 
 ---
 
-**Version**: 3.6.60
-**Last Updated**: 2026-03-19
+**Version**: 3.6.61
+**Last Updated**: 2026-03-20

package/README.zh.md

@@ -179,7 +179,7 @@ SCE 默认是强治理的。
 - `sce app registry status|configure|sync*`
 - `sce app runtime show|releases|install|activate|uninstall`
 - `sce app engineering preview|ownership|open|import|show|attach|hydrate|scaffold|activate`
-- `sce project portfolio show|target resolve|supervision show`
+- `sce project portfolio show|candidate inspect|onboarding import|target resolve|supervision show`
 - `sce mode application|ontology|engineering home`
 - `sce pm requirement|tracking|planning|change|issue ... --json`
 - `sce ontology er|br|dl ... --json`
@@ -235,5 +235,5 @@ MIT，见 [LICENSE](LICENSE)。
 
 ---
 
-**版本**：3.6.60
-**最后更新**：2026-03-19
+**版本**：3.6.61
+**最后更新**：2026-03-20

package/docs/command-reference.md

@@ -2660,7 +2660,7 @@ Overall Health: 2 healthy, 1 unhealthy
 
 ---
 
-## Project Portfolio And Supervision
+## Project Portfolio, Candidate Inspection, And Onboarding
 
 #### `sce project portfolio show`
 
@@ -2680,6 +2680,42 @@ sce project portfolio show [options]
 - Marks inaccessible or partial projects explicitly instead of dropping them
 - Reuses project-local session governance signals to summarize active sessions and last activity
 
+#### `sce project candidate inspect`
+
+Inspect one local root through the canonical engine-owned project-candidate contract.
+
+**Usage:**
+```bash
+sce project candidate inspect --root <path> [options]
+```
+
+**Options:**
+- `--root <path>` - Local root directory to inspect
+- `--json` - Output the canonical `LocalProjectCandidateInspection`
+
+**Behavior:**
+- Distinguishes `workspace-backed`, `local-sce-candidate`, `directory-candidate`, and `invalid`
+- Reuses deterministic project/workspace identity when the root already maps to a registered workspace
+- Returns canonical readiness, availability, and reason codes without adapter-side path heuristics
+
+#### `sce project onboarding import`
+
+Import one local root into the canonical project portfolio using root-based onboarding.
+
+**Usage:**
+```bash
+sce project onboarding import --root <path> [options]
+```
+
+**Options:**
+- `--root <path>` - Local root directory to import
+- `--json` - Output the canonical `ProjectOnboardingImportResult`
+
+**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
+
 #### `sce project target resolve`
 
 Resolve one target project for cross-project flows without mutating active workspace selection.

package/docs/magicball-adaptation-task-checklist-v1.md

@@ -68,6 +68,20 @@ Done when:
 - drillback panels use `items[]` directly
 - frontend does not present `cursor` as a raw event-stream offset
 
+### Task 0.5
+Preflight user-picked local roots with the canonical candidate contract, then onboard by root when needed.
+
+Commands:
+```bash
+sce project candidate inspect --root "<path>" --json
+sce project onboarding import --root "<path>" --json
+```
+
+Done when:
+- frontend does not infer project validity from ad hoc `.sce` path heuristics alone
+- existing local `.sce` roots are imported without rebuilding them blindly
+- ordinary directories can be onboarded without pretending to be app-library items first
+
 ## Phase 1: App Entry And Mode Switching
 
 ### Task 1.1

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

@@ -24,6 +24,8 @@ Assume:
 ### 1.0 Read multi-project portfolio baseline
 ```bash
 sce project portfolio show --json
+sce project candidate inspect --root "C:/workspace/customer-order-demo" --json
+sce project onboarding import --root "C:/workspace/customer-order-demo" --json
 sce project target resolve --request "continue customer-order-demo" --json
 sce project supervision show --project workspace:customer-order-demo --json
 ```

package/docs/magicball-frontend-state-and-command-mapping.md

@@ -65,6 +65,8 @@ Recommended shape:
 ```ts
 interface ProjectWorkspaceShellState {
   projectPortfolio: Record<string, unknown> | null
+  projectCandidate: Record<string, unknown> | null
+  projectOnboarding: Record<string, unknown> | null
   currentProjectId: string | null
   projectTarget: Record<string, unknown> | null
   projectSupervision: Record<string, unknown> | null
@@ -73,11 +75,14 @@ interface ProjectWorkspaceShellState {
 
 Owned commands:
 - `sce project portfolio show --json`
+- `sce project candidate inspect --root <path> --json`
+- `sce project onboarding import --root <path> --json`
 - `sce project target resolve --request <text> --current-project <project-id> --json`
 - `sce project supervision show --project <project-id> --json`
 
 Rule:
 - multi-project shell must consume engine-owned project truth directly
+- manual local-root import must preflight with `candidate inspect` before any onboarding mutation
 - target resolution must be treated as preflight and must not mutate active workspace selection implicitly
 
 ### 2.2 Ontology Page State

package/docs/magicball-integration-issue-tracker.md

@@ -29,7 +29,7 @@ SCE changes completed and now available for MagicBall:
 - `app registry status/configure/sync*`
 - `app runtime show/releases/install/activate/uninstall`
 - `app engineering preview/ownership/open/import/show/attach/hydrate/scaffold/activate`
-- `project portfolio show/target resolve/supervision show`
+- `project portfolio show/candidate inspect/onboarding import/target resolve/supervision show`
 - `pm requirement/tracking/planning/change/issue` data plane
 - `ontology er/br/dl` + `ontology triad summary`
 - `ontology seed list/show/apply`
@@ -41,7 +41,7 @@ SCE changes completed and now available for MagicBall:
 2. consume `device current`, `app collection list/show/apply`, `scene workspace list/show/apply`, and `app install-state list` as the local device/install baseline
 3. consume `pm`, `ontology`, and `assurance` table payloads
 4. wire runtime install/activate/uninstall and engineering attach/hydrate/scaffold/activate actions
-5. treat `project portfolio / target resolve / supervision` as the default multi-project shell truth
+5. treat `project portfolio / candidate inspect / onboarding import / target resolve / supervision` as the default multi-project shell truth
 6. use demo app: `customer-order-demo`
 
 ### Related SCE docs

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

@@ -6,6 +6,8 @@ Define the stable phase-1 SCE contract for MagicBall multi-project surfaces.
 
 This document covers:
 - project roster projection
+- root candidate inspection
+- root-based onboarding import
 - target-project preflight resolution
 - project-scoped supervision snapshot
 
@@ -22,6 +24,7 @@ Use together with:
 
 Phase-1 is read-first and engine-owned:
 - project visibility comes from registered workspaces plus the current unregistered `.sce` project when applicable
+- local root inspection and onboarding reuse engine-owned identity and reason codes
 - project identity is deterministic and stable for registered workspaces
 - target resolution is preflight-only and does not mutate active workspace selection
 - supervision is a project-scoped snapshot, not a raw cross-project event stream
@@ -36,6 +39,8 @@ Phase-1 does not introduce:
 
 ```bash
 sce project portfolio show --json
+sce project candidate inspect --root <path> --json
+sce project onboarding import --root <path> --json
 sce project target resolve --json
 sce project supervision show --project <project-id> --json
 ```
@@ -105,6 +110,55 @@ interface ProjectPortfolioRecord {
 
 ## 2. Target Resolution
 
+## 1.5 Root Candidate Inspection And Onboarding
+
+### Commands
+
+```bash
+sce project candidate inspect --root <path> --json
+sce project onboarding import --root <path> --json
+```
+
+### Contract shape
+
+```ts
+interface LocalProjectCandidateInspection {
+  inspectedAt: string
+  rootDir: string
+  kind: 'workspace-backed' | 'local-sce-candidate' | 'directory-candidate' | 'invalid'
+  projectId?: string
+  workspaceId?: string
+  projectName?: string
+  readiness: 'ready' | 'partial' | 'pending' | 'blocked' | 'unknown'
+  availability: 'accessible' | 'inaccessible' | 'degraded'
+  localCandidate: boolean
+  reasonCodes: string[]
+}
+
+interface ProjectOnboardingImportResult {
+  mode: 'import'
+  generated_at: string
+  success: boolean
+  preview: LocalProjectCandidateInspection
+  steps: Array<{
+    key: 'register' | 'attach' | 'hydrate' | 'activate' | 'scaffold'
+    status: 'done' | 'skipped' | 'pending' | 'failed'
+    reasonCode?: string
+    detail?: string
+  }>
+}
+```
+
+### MagicBall rules
+
+- Adapter-owned filesystem scanning is allowed, but every chosen root must be normalized through `candidate inspect`.
+- 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.
+- Render `reasonCodes` directly in CLI/IDE receipts; do not replace them with frontend-only heuristics.
+
+## 2. Target Resolution
+
 ### Command
 
 ```bash
@@ -201,10 +255,12 @@ interface ProjectSupervisionItem {
 ## 4. Recommended Multi-Project Frontend Flow
 
 1. Load `sce project portfolio show --json` when entering the multi-project shell.
-2. Store `activeProjectId` and render a project switcher from `projects[]`.
-3. When the user enters a cross-project free-text request, preflight with `sce project target resolve --json`.
-4. After project selection or successful resolution, load `sce project supervision show --project <project-id> --json`.
-5. Keep per-project tabs and page layout frontend-owned, but keep project truth engine-owned.
+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`.
+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`.
+7. Keep per-project tabs and page layout frontend-owned, but keep project truth engine-owned.
 
 ## 5. Minimal Acceptance Criteria For MagicBall
 

package/docs/magicball-sce-adaptation-guide.md

@@ -142,6 +142,8 @@ Use `docs/magicball-cli-invocation-examples.md` for copy-ready commands.
 
 ### Multi-project control
 - `sce project portfolio show`
+- `sce project candidate inspect`
+- `sce project onboarding import`
 - `sce project target resolve`
 - `sce project supervision show`
 

package/docs/magicball-ui-surface-checklist.md

@@ -136,11 +136,13 @@ MagicBall can treat the current SCE integration as baseline-ready when:
 
 ### Must render
 - project switcher from `project portfolio show`
+- local-root candidate receipt from `project candidate inspect`
 - current project marker
 - project health summary from `project supervision show`
 - explicit degraded / inaccessible project states
 
 ### Must behave correctly
+- manual root import preflights through `project candidate inspect` before `project onboarding import`
 - cross-project free-text routing preflights through `project target resolve`
 - ambiguous resolution does not auto-select silently
 - target resolution does not implicitly switch active workspace selection

package/docs/release-checklist.md

@@ -94,7 +94,7 @@ rg -n "github.com/scene-capability-engine/sce" README.md README.zh.md docs START
 Additional expectation:
 
 - `audit:magicball-engineering-contract` passes so active MagicBall entry docs stay aligned with `scene delivery`, `engineering preview/ownership`, and `open/import/scaffold` contracts.
-- `audit:magicball-project-contract` passes so active MagicBall entry docs stay aligned with `project portfolio`, `project target resolve`, and `project supervision show` contracts.
+- `audit:magicball-project-contract` passes so active MagicBall entry docs stay aligned with `project portfolio`, `project candidate inspect`, `project onboarding import`, `project target resolve`, and `project supervision show` contracts.
 
 ---
 

package/docs/releases/README.md

@@ -9,6 +9,7 @@ This directory stores release-facing documents:
 ## Archived Versions
 
 - [Release checklist](../release-checklist.md)
+- [v3.6.61 release notes](./v3.6.61.md)
 - [v3.6.60 release notes](./v3.6.60.md)
 - [v3.6.59 release notes](./v3.6.59.md)
 - [v3.6.58 release notes](./v3.6.58.md)

package/docs/releases/v3.6.61.md

@@ -0,0 +1,21 @@
+# v3.6.61 Release Notes
+
+Release date: 2026-03-20
+
+## Highlights
+
+- Added canonical local-root inspection through `sce project candidate inspect --root <path> --json`, so adapters can classify one chosen directory without inventing their own `.sce` heuristics.
+- Added canonical root-based onboarding through `sce project onboarding import --root <path> --json`, reusing the shared onboarding step envelope and registering imported roots into the project portfolio without a second registry.
+- Extended MagicBall-facing contract docs and release-time doc audit to keep `candidate inspect` and `onboarding import` aligned with `project portfolio / target resolve / supervision`.
+
+## Validation
+
+- `npx jest tests/unit/commands/project.test.js --runInBand`
+- `npx jest tests/unit/scripts/magicball-project-contract-audit.test.js --runInBand`
+- `npx jest tests/integration/project-cli.integration.test.js --runInBand`
+- `node scripts/magicball-project-contract-audit.js --fail-on-violation --json`
+
+## Release Notes
+
+- Use `v3.6.61` when you need the upstream `136-00` local-project candidate inspection and root-based onboarding contract in the published SCE package.
+- This release stays within the existing engine/adapter boundary: adapters still own scan policy, while SCE now owns the canonical semantics for inspecting one root and importing it by root.

package/docs/zh/release-checklist.md

@@ -79,7 +79,7 @@ rg -n "github.com/scene-capability-engine/sce" README.md README.zh.md docs START
 额外预期：
 
 - `audit:magicball-engineering-contract` 通过，确保活跃的 MagicBall 入口文档与 `scene delivery`、`engineering preview/ownership`、`open/import/scaffold` 契约保持一致。
-- `audit:magicball-project-contract` 通过，确保活跃的 MagicBall 入口文档与 `project portfolio`、`project target resolve`、`project supervision show` 契约保持一致。
+- `audit:magicball-project-contract` 通过，确保活跃的 MagicBall 入口文档与 `project portfolio`、`project candidate inspect`、`project onboarding import`、`project target resolve`、`project supervision show` 契约保持一致。
 
 ---
 

package/docs/zh/releases/README.md

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

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

@@ -0,0 +1,21 @@
+# v3.6.61 发布说明
+
+发布日期：2026-03-20
+
+## 重点变化
+
+- 新增 `sce project candidate inspect --root <path> --json`，把“单个本地目录候选项目检查”正式上收到 engine 契约层，适配器不再需要自造 `.sce` 目录启发式。
+- 新增 `sce project onboarding import --root <path> --json`，把“按根目录导入/onboarding”正式收敛到 canonical step envelope，并把导入结果纳入项目 portfolio，而不是另造第二套 registry。
+- 同步扩展了 MagicBall 多项目合同文档与发布时项目合同审计，确保 `candidate inspect / onboarding import` 与既有 `project portfolio / target resolve / supervision` 保持一致。
+
+## 验证
+
+- `npx jest tests/unit/commands/project.test.js --runInBand`
+- `npx jest tests/unit/scripts/magicball-project-contract-audit.test.js --runInBand`
+- `npx jest tests/integration/project-cli.integration.test.js --runInBand`
+- `node scripts/magicball-project-contract-audit.js --fail-on-violation --json`
+
+## 发布说明
+
+- 需要上游 `136-00` 本地项目候选检查与按根目录 onboarding 契约时，请使用 `v3.6.61`。
+- 该版本继续保持 engine / adapter 边界：扫描策略仍归适配器，SCE 负责“检查一个 root”和“按 root 导入”的正式语义。

package/lib/commands/project.js

@@ -1,5 +1,7 @@
 const chalk = require('chalk');
+const { inspectProjectCandidate } = require('../project/candidate-inspection-service');
 const { buildProjectPortfolioProjection } = require('../project/portfolio-projection-service');
+const { runProjectRootOnboardingImport } = require('../project/root-onboarding-service');
 const { buildProjectSupervisionProjection } = require('../project/supervision-projection-service');
 const { resolveProjectTarget } = require('../project/target-resolution-service');
 
@@ -41,6 +43,32 @@ async function runProjectSupervisionShowCommand(options = {}, dependencies = {})
   return payload;
 }
 
+async function runProjectCandidateInspectCommand(options = {}, dependencies = {}) {
+  const payload = await inspectProjectCandidate(options, dependencies);
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(chalk.blue('Project Candidate Inspection'));
+    console.log(`  Root: ${payload.rootDir}`);
+    console.log(`  Kind: ${payload.kind}`);
+    console.log(`  Readiness: ${payload.readiness}`);
+  }
+  return payload;
+}
+
+async function runProjectOnboardingImportCommand(options = {}, dependencies = {}) {
+  const payload = await runProjectRootOnboardingImport(options, dependencies);
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    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(`  Workspace: ${payload.result && payload.result.workspaceId ? payload.result.workspaceId : 'none'}`);
+  }
+  return payload;
+}
+
 function safeRun(handler, options = {}, context = 'project command') {
   Promise.resolve(handler(options))
     .catch((error) => {
@@ -84,6 +112,28 @@ function registerProjectCommands(program) {
     .option('--json', 'Print machine-readable JSON output')
     .action((options) => safeRun(runProjectTargetResolveCommand, options, 'project target resolve'));
 
+  const candidate = project
+    .command('candidate')
+    .description('Inspect one local directory as a canonical project candidate');
+
+  candidate
+    .command('inspect')
+    .description('Inspect one local root without inventing adapter-side heuristics')
+    .requiredOption('--root <path>', 'Local root directory to inspect')
+    .option('--json', 'Print machine-readable JSON output')
+    .action((options) => safeRun(runProjectCandidateInspectCommand, options, 'project candidate inspect'));
+
+  const onboarding = project
+    .command('onboarding')
+    .description('Import one local directory into the canonical project portfolio');
+
+  onboarding
+    .command('import')
+    .description('Run root-based onboarding without app-bundle-first indirection')
+    .requiredOption('--root <path>', 'Local root directory to import')
+    .option('--json', 'Print machine-readable JSON output')
+    .action((options) => safeRun(runProjectOnboardingImportCommand, options, 'project onboarding import'));
+
   const supervision = project
     .command('supervision')
     .description('Inspect project-scoped supervision projection');
@@ -98,6 +148,8 @@ function registerProjectCommands(program) {
 }
 
 module.exports = {
+  runProjectCandidateInspectCommand,
+  runProjectOnboardingImportCommand,
   runProjectPortfolioShowCommand,
   runProjectTargetResolveCommand,
   runProjectSupervisionShowCommand,

package/lib/project/candidate-inspection-service.js

@@ -0,0 +1,216 @@
+const path = require('path');
+const fs = require('fs-extra');
+const WorkspaceStateManager = require('../workspace/multi/workspace-state-manager');
+const {
+  buildLocalProjectId,
+  buildWorkspaceProjectId
+} = require('./portfolio-projection-service');
+
+const PROJECT_CANDIDATE_REASON_CODES = {
+  ROOT_ACCESSIBLE: 'project.root.accessible',
+  ROOT_INACCESSIBLE: 'project.root.inaccessible',
+  ROOT_INVALID_TYPE: 'project.root.invalid_type',
+  WORKSPACE_REGISTERED: 'project.workspace.registered',
+  SCE_PRESENT: 'project.sce.present',
+  ROOT_NOT_INITIALIZED: 'project.root.not_initialized',
+  INVALID_PROJECT_METADATA: 'project.metadata.invalid',
+  UNREGISTERED_PROJECT: 'project.sce.unregistered'
+};
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function normalizePath(value) {
+  return normalizeString(value).replace(/\\/g, '/');
+}
+
+function buildProjectName(rootDir) {
+  return path.basename(rootDir) || 'project';
+}
+
+async function resolveExactWorkspaceByRoot(rootDir, stateManager) {
+  const workspaces = await stateManager.listWorkspaces();
+  const normalizedRoot = normalizePath(rootDir);
+  return workspaces.find((workspace) => normalizePath(workspace && workspace.path) === normalizedRoot) || null;
+}
+
+async function inspectSceMetadata(rootDir, fileSystem = fs) {
+  const sceRoot = path.join(rootDir, '.sce');
+  if (!await fileSystem.pathExists(sceRoot)) {
+    return {
+      scePresent: false,
+      metadataValid: true,
+      metadataReasonCodes: []
+    };
+  }
+
+  try {
+    const sceStats = await fileSystem.stat(sceRoot);
+    if (!sceStats.isDirectory()) {
+      return {
+        scePresent: false,
+        metadataValid: false,
+        metadataReasonCodes: [PROJECT_CANDIDATE_REASON_CODES.ROOT_INVALID_TYPE]
+      };
+    }
+  } catch (_error) {
+    return {
+      scePresent: false,
+      metadataValid: false,
+      metadataReasonCodes: [PROJECT_CANDIDATE_REASON_CODES.ROOT_INACCESSIBLE]
+    };
+  }
+
+  const versionPath = path.join(sceRoot, 'version.json');
+  if (!await fileSystem.pathExists(versionPath)) {
+    return {
+      scePresent: true,
+      metadataValid: true,
+      metadataReasonCodes: [PROJECT_CANDIDATE_REASON_CODES.SCE_PRESENT]
+    };
+  }
+
+  try {
+    await fileSystem.readJson(versionPath);
+    return {
+      scePresent: true,
+      metadataValid: true,
+      metadataReasonCodes: [PROJECT_CANDIDATE_REASON_CODES.SCE_PRESENT]
+    };
+  } catch (_error) {
+    return {
+      scePresent: true,
+      metadataValid: false,
+      metadataReasonCodes: [
+        PROJECT_CANDIDATE_REASON_CODES.SCE_PRESENT,
+        PROJECT_CANDIDATE_REASON_CODES.INVALID_PROJECT_METADATA
+      ]
+    };
+  }
+}
+
+function dedupeReasonCodes(reasonCodes = []) {
+  return Array.from(new Set(reasonCodes.filter(Boolean)));
+}
+
+async function inspectProjectCandidate(options = {}, dependencies = {}) {
+  const fileSystem = dependencies.fileSystem || fs;
+  const stateManager = dependencies.stateManager || new WorkspaceStateManager(dependencies.workspaceStatePath);
+  const requestedRoot = normalizeString(options.root || options.rootDir);
+  if (!requestedRoot) {
+    throw new Error('--root is required');
+  }
+
+  const absoluteRoot = path.resolve(requestedRoot);
+  const rootDir = normalizePath(absoluteRoot);
+  const inspectedAt = new Date().toISOString();
+  const projectName = buildProjectName(rootDir);
+
+  if (!await fileSystem.pathExists(absoluteRoot)) {
+    return {
+      inspectedAt,
+      rootDir,
+      kind: 'invalid',
+      projectName,
+      readiness: 'blocked',
+      availability: 'inaccessible',
+      localCandidate: false,
+      reasonCodes: [PROJECT_CANDIDATE_REASON_CODES.ROOT_INACCESSIBLE]
+    };
+  }
+
+  let rootStats = null;
+  try {
+    rootStats = await fileSystem.stat(absoluteRoot);
+  } catch (_error) {
+    return {
+      inspectedAt,
+      rootDir,
+      kind: 'invalid',
+      projectName,
+      readiness: 'blocked',
+      availability: 'inaccessible',
+      localCandidate: false,
+      reasonCodes: [PROJECT_CANDIDATE_REASON_CODES.ROOT_INACCESSIBLE]
+    };
+  }
+
+  if (!rootStats.isDirectory()) {
+    return {
+      inspectedAt,
+      rootDir,
+      kind: 'invalid',
+      projectName,
+      readiness: 'blocked',
+      availability: 'degraded',
+      localCandidate: false,
+      reasonCodes: [PROJECT_CANDIDATE_REASON_CODES.ROOT_INVALID_TYPE]
+    };
+  }
+
+  const workspace = await resolveExactWorkspaceByRoot(absoluteRoot, stateManager);
+  const sceInspection = await inspectSceMetadata(absoluteRoot, fileSystem);
+  const metadataBlocked = sceInspection.scePresent && !sceInspection.metadataValid;
+
+  if (workspace) {
+    const workspaceBlocked = !sceInspection.scePresent || metadataBlocked;
+    return {
+      inspectedAt,
+      rootDir,
+      kind: 'workspace-backed',
+      projectId: buildWorkspaceProjectId(workspace.name),
+      workspaceId: workspace.name,
+      projectName,
+      readiness: workspaceBlocked ? 'blocked' : 'ready',
+      availability: workspaceBlocked ? 'degraded' : 'accessible',
+      localCandidate: false,
+      reasonCodes: dedupeReasonCodes([
+        PROJECT_CANDIDATE_REASON_CODES.WORKSPACE_REGISTERED,
+        PROJECT_CANDIDATE_REASON_CODES.ROOT_ACCESSIBLE,
+        ...(!sceInspection.scePresent ? [PROJECT_CANDIDATE_REASON_CODES.ROOT_NOT_INITIALIZED] : []),
+        ...sceInspection.metadataReasonCodes
+      ])
+    };
+  }
+
+  if (sceInspection.scePresent) {
+    return {
+      inspectedAt,
+      rootDir,
+      kind: 'local-sce-candidate',
+      projectId: buildLocalProjectId(rootDir),
+      projectName,
+      readiness: metadataBlocked ? 'blocked' : 'partial',
+      availability: metadataBlocked ? 'degraded' : 'degraded',
+      localCandidate: true,
+      reasonCodes: dedupeReasonCodes([
+        PROJECT_CANDIDATE_REASON_CODES.ROOT_ACCESSIBLE,
+        PROJECT_CANDIDATE_REASON_CODES.UNREGISTERED_PROJECT,
+        ...sceInspection.metadataReasonCodes
+      ])
+    };
+  }
+
+  return {
+    inspectedAt,
+    rootDir,
+    kind: 'directory-candidate',
+    projectName,
+    readiness: 'pending',
+    availability: 'accessible',
+    localCandidate: true,
+    reasonCodes: [
+      PROJECT_CANDIDATE_REASON_CODES.ROOT_ACCESSIBLE,
+      PROJECT_CANDIDATE_REASON_CODES.ROOT_NOT_INITIALIZED
+    ]
+  };
+}
+
+module.exports = {
+  PROJECT_CANDIDATE_REASON_CODES,
+  inspectProjectCandidate
+};

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

@@ -0,0 +1,350 @@
+const path = require('path');
+const fs = require('fs-extra');
+const WorkspaceStateManager = require('../workspace/multi/workspace-state-manager');
+const SmartOrchestrator = require('../adoption/smart-orchestrator');
+const { applyTakeoverBaseline } = require('../workspace/takeover-baseline');
+const {
+  PROJECT_CANDIDATE_REASON_CODES,
+  inspectProjectCandidate
+} = require('./candidate-inspection-service');
+const {
+  buildWorkspaceProjectId
+} = require('./portfolio-projection-service');
+
+const PROJECT_ONBOARDING_REASON_CODES = {
+  MISSING_ROOT: 'project.onboarding.blocked.missing_root',
+  BLOCKED_BY_CANDIDATE: 'project.onboarding.blocked.candidate_state',
+  ROOT_ACCEPTED: 'project.onboarding.root_accepted',
+  IMPORT_NO_ACTIVATE: 'project.onboarding.import_no_activate',
+  REGISTERED: 'project.onboarding.registered',
+  ADOPTED: 'project.onboarding.adopted',
+  SCAFFOLD_REUSED: 'project.onboarding.scaffold_reused',
+  ADOPTION_FAILED: 'project.onboarding.adoption_failed'
+};
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function buildStep(key, status, detail, reasonCode) {
+  return {
+    key,
+    status,
+    ...(reasonCode ? { reasonCode } : {}),
+    ...(detail ? { detail } : {})
+  };
+}
+
+function buildWorkspaceNameCandidate(rootDir) {
+  const base = path.basename(rootDir).trim().toLowerCase();
+  const normalized = base.replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+  return normalized || 'project';
+}
+
+async function allocateWorkspaceId(rootDir, stateManager) {
+  const base = buildWorkspaceNameCandidate(rootDir);
+  if (!await stateManager.hasWorkspace(base)) {
+    return base;
+  }
+
+  for (let index = 2; index < 1000; index += 1) {
+    const candidate = `${base}-${index}`;
+    if (!await stateManager.hasWorkspace(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new Error(`unable to allocate workspace id for root: ${rootDir}`);
+}
+
+function buildFailureEnvelope(rootInspection, steps, detail, reasonCode) {
+  return {
+    mode: 'import',
+    generated_at: new Date().toISOString(),
+    success: false,
+    preview: rootInspection,
+    summary: rootInspection,
+    steps,
+    error: {
+      reasonCode,
+      detail
+    }
+  };
+}
+
+async function runWithSuppressedConsole(callback, enabled) {
+  if (!enabled) {
+    return callback();
+  }
+
+  const originalLog = console.log;
+  const originalInfo = console.info;
+  const originalWarn = console.warn;
+  console.log = () => {};
+  console.info = () => {};
+  console.warn = () => {};
+  try {
+    return await callback();
+  } finally {
+    console.log = originalLog;
+    console.info = originalInfo;
+    console.warn = originalWarn;
+  }
+}
+
+async function runProjectRootOnboardingImport(options = {}, dependencies = {}) {
+  const fileSystem = dependencies.fileSystem || fs;
+  const stateManager = dependencies.stateManager || new WorkspaceStateManager(dependencies.workspaceStatePath);
+  const root = normalizeString(options.root || options.rootDir);
+  if (!root) {
+    throw new Error('--root is required');
+  }
+
+  const rootInspection = await inspectProjectCandidate({ root }, {
+    ...dependencies,
+    fileSystem,
+    stateManager
+  });
+  const steps = [];
+
+  if (rootInspection.kind === 'invalid') {
+    steps.push(buildStep(
+      'register',
+      'failed',
+      'Root directory cannot be onboarded.',
+      PROJECT_ONBOARDING_REASON_CODES.BLOCKED_BY_CANDIDATE
+    ));
+    steps.push(buildStep(
+      'attach',
+      'failed',
+      'Local root is not accessible as a project directory.',
+      PROJECT_CANDIDATE_REASON_CODES.ROOT_INACCESSIBLE
+    ));
+    steps.push(buildStep(
+      'hydrate',
+      'failed',
+      'Onboarding cannot continue until the root is valid.',
+      PROJECT_ONBOARDING_REASON_CODES.BLOCKED_BY_CANDIDATE
+    ));
+    steps.push(buildStep(
+      'activate',
+      'skipped',
+      'Import does not activate invalid roots.',
+      PROJECT_ONBOARDING_REASON_CODES.IMPORT_NO_ACTIVATE
+    ));
+    steps.push(buildStep(
+      'scaffold',
+      'skipped',
+      'Scaffold is blocked until the root becomes valid.',
+      PROJECT_ONBOARDING_REASON_CODES.BLOCKED_BY_CANDIDATE
+    ));
+    return buildFailureEnvelope(
+      rootInspection,
+      steps,
+      'Root inspection reported an invalid candidate state.',
+      PROJECT_ONBOARDING_REASON_CODES.BLOCKED_BY_CANDIDATE
+    );
+  }
+
+  if (rootInspection.reasonCodes.includes(PROJECT_CANDIDATE_REASON_CODES.INVALID_PROJECT_METADATA)) {
+    steps.push(buildStep(
+      'register',
+      'failed',
+      'Root contains invalid SCE metadata and cannot be imported safely.',
+      PROJECT_CANDIDATE_REASON_CODES.INVALID_PROJECT_METADATA
+    ));
+    steps.push(buildStep(
+      'attach',
+      'done',
+      'Local root is reachable.',
+      PROJECT_ONBOARDING_REASON_CODES.ROOT_ACCEPTED
+    ));
+    steps.push(buildStep(
+      'hydrate',
+      'failed',
+      'Existing project metadata must be repaired before import.',
+      PROJECT_CANDIDATE_REASON_CODES.INVALID_PROJECT_METADATA
+    ));
+    steps.push(buildStep(
+      'activate',
+      'skipped',
+      'Import does not activate blocked projects.',
+      PROJECT_ONBOARDING_REASON_CODES.IMPORT_NO_ACTIVATE
+    ));
+    steps.push(buildStep(
+      'scaffold',
+      'skipped',
+      'Scaffold is blocked by invalid project metadata.',
+      PROJECT_CANDIDATE_REASON_CODES.INVALID_PROJECT_METADATA
+    ));
+    return buildFailureEnvelope(
+      rootInspection,
+      steps,
+      'Existing project metadata is invalid.',
+      PROJECT_CANDIDATE_REASON_CODES.INVALID_PROJECT_METADATA
+    );
+  }
+
+  let onboardingPreview = { ...rootInspection };
+  let importResult = null;
+  let takeoverBaseline = null;
+
+  if (rootInspection.kind === 'directory-candidate') {
+    const orchestrator = dependencies.smartOrchestrator || new SmartOrchestrator();
+    importResult = await runWithSuppressedConsole(() => orchestrator.orchestrate(rootInspection.rootDir, {
+      dryRun: false,
+      verbose: false,
+      skipBackup: false,
+      skipUpdate: false
+    }), options.json === true);
+
+    if (!importResult.success) {
+      steps.push(buildStep(
+        'register',
+        'failed',
+        'Workspace registration was not attempted because adoption failed.',
+        PROJECT_ONBOARDING_REASON_CODES.ADOPTION_FAILED
+      ));
+      steps.push(buildStep(
+        'attach',
+        'done',
+        'Local root is reachable.',
+        PROJECT_ONBOARDING_REASON_CODES.ROOT_ACCEPTED
+      ));
+      steps.push(buildStep(
+        'hydrate',
+        'failed',
+        (importResult.errors || []).join('; ') || 'Adoption failed.',
+        PROJECT_ONBOARDING_REASON_CODES.ADOPTION_FAILED
+      ));
+      steps.push(buildStep(
+        'activate',
+        'skipped',
+        'Import does not activate failed onboarding results.',
+        PROJECT_ONBOARDING_REASON_CODES.IMPORT_NO_ACTIVATE
+      ));
+      steps.push(buildStep(
+        'scaffold',
+        'failed',
+        'SCE baseline could not be applied to the root directory.',
+        PROJECT_ONBOARDING_REASON_CODES.ADOPTION_FAILED
+      ));
+      return buildFailureEnvelope(
+        rootInspection,
+        steps,
+        (importResult.errors || []).join('; ') || 'Adoption failed.',
+        PROJECT_ONBOARDING_REASON_CODES.ADOPTION_FAILED
+      );
+    }
+
+    const packageJson = require('../../package.json');
+    takeoverBaseline = await applyTakeoverBaseline(rootInspection.rootDir, {
+      apply: true,
+      writeReport: true,
+      sceVersion: packageJson.version
+    });
+    onboardingPreview = await inspectProjectCandidate({ root: rootInspection.rootDir }, {
+      ...dependencies,
+      fileSystem,
+      stateManager
+    });
+  }
+
+  let workspaceId = rootInspection.workspaceId || null;
+  if (!workspaceId) {
+    workspaceId = await allocateWorkspaceId(rootInspection.rootDir, stateManager);
+    await stateManager.createWorkspace(workspaceId, rootInspection.rootDir);
+    onboardingPreview = {
+      ...onboardingPreview,
+      kind: 'workspace-backed',
+      projectId: buildWorkspaceProjectId(workspaceId),
+      workspaceId,
+      readiness: onboardingPreview.kind === 'directory-candidate' ? 'ready' : onboardingPreview.readiness,
+      availability: 'accessible',
+      localCandidate: false,
+      reasonCodes: Array.from(new Set([
+        PROJECT_CANDIDATE_REASON_CODES.WORKSPACE_REGISTERED,
+        ...onboardingPreview.reasonCodes
+      ]))
+    };
+  }
+
+  steps.push(buildStep(
+    'register',
+    'done',
+    rootInspection.workspaceId
+      ? 'Workspace was already registered.'
+      : `Workspace registered as ${workspaceId}.`,
+    rootInspection.workspaceId
+      ? PROJECT_CANDIDATE_REASON_CODES.WORKSPACE_REGISTERED
+      : PROJECT_ONBOARDING_REASON_CODES.REGISTERED
+  ));
+  steps.push(buildStep(
+    'attach',
+    'done',
+    'Local root is accepted as the canonical onboarding source.',
+    PROJECT_ONBOARDING_REASON_CODES.ROOT_ACCEPTED
+  ));
+  steps.push(buildStep(
+    'hydrate',
+    'done',
+    rootInspection.kind === 'directory-candidate'
+      ? 'SCE baseline and project hydration were applied to the root directory.'
+      : 'Existing SCE project root is ready for portfolio import.',
+    rootInspection.kind === 'directory-candidate'
+      ? PROJECT_ONBOARDING_REASON_CODES.ADOPTED
+      : PROJECT_CANDIDATE_REASON_CODES.SCE_PRESENT
+  ));
+  steps.push(buildStep(
+    'activate',
+    'skipped',
+    'Import keeps active workspace selection unchanged in phase-1.',
+    PROJECT_ONBOARDING_REASON_CODES.IMPORT_NO_ACTIVATE
+  ));
+  steps.push(buildStep(
+    'scaffold',
+    rootInspection.kind === 'directory-candidate' ? 'done' : 'skipped',
+    rootInspection.kind === 'directory-candidate'
+      ? 'Applied SCE baseline files to the project root.'
+      : 'Existing SCE baseline is reused; no scaffold rewrite was required.',
+    rootInspection.kind === 'directory-candidate'
+      ? PROJECT_ONBOARDING_REASON_CODES.ADOPTED
+      : PROJECT_ONBOARDING_REASON_CODES.SCAFFOLD_REUSED
+  ));
+
+  return {
+    mode: 'import',
+    generated_at: new Date().toISOString(),
+    success: true,
+    preview: onboardingPreview,
+    summary: onboardingPreview,
+    steps,
+    result: {
+      rootDir: onboardingPreview.rootDir,
+      projectId: onboardingPreview.projectId || null,
+      workspaceId: onboardingPreview.workspaceId || null,
+      ...(importResult ? {
+        adoption: {
+          mode: importResult.mode || null,
+          backupId: importResult.backup ? importResult.backup.id : null,
+          changes: importResult.changes || { created: [], updated: [], deleted: [], preserved: [] },
+          warnings: importResult.warnings || []
+        }
+      } : {}),
+      ...(takeoverBaseline ? {
+        takeoverBaseline: {
+          reportFile: takeoverBaseline.report_file || null,
+          summary: takeoverBaseline.summary || {}
+        }
+      } : {})
+    }
+  };
+}
+
+module.exports = {
+  PROJECT_ONBOARDING_REASON_CODES,
+  runProjectRootOnboardingImport
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scene-capability-engine",
-  "version": "3.6.60",
+  "version": "3.6.61",
   "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/magicball-project-contract-audit.js

@@ -8,19 +8,21 @@ const REQUIRED_CHECKS = [
   {
     path: 'README.md',
     requiredSnippets: [
-      '`sce project portfolio show|target resolve|supervision show`'
+      '`sce project portfolio show|candidate inspect|onboarding import|target resolve|supervision show`'
     ]
   },
   {
     path: 'README.zh.md',
     requiredSnippets: [
-      '`sce project portfolio show|target resolve|supervision show`'
+      '`sce project portfolio show|candidate inspect|onboarding import|target resolve|supervision show`'
     ]
   },
   {
     path: 'docs/command-reference.md',
     requiredSnippets: [
       'sce project portfolio show [options]',
+      'sce project candidate inspect --root <path> [options]',
+      'sce project onboarding import --root <path> [options]',
       'sce project target resolve [options]',
       'sce project supervision show --project <id> [options]'
     ]
@@ -45,6 +47,8 @@ const REQUIRED_CHECKS = [
     path: 'docs/magicball-project-portfolio-contract.md',
     requiredSnippets: [
       'sce project portfolio show --json',
+      'sce project candidate inspect --root <path> --json',
+      'sce project onboarding import --root <path> --json',
       'sce project target resolve --json',
       'sce project supervision show --project <project-id> --json'
     ]
@@ -53,7 +57,11 @@ const REQUIRED_CHECKS = [
     path: 'docs/magicball-frontend-state-and-command-mapping.md',
     requiredSnippets: [
       'projectPortfolio: Record<string, unknown> | null',
+      'projectCandidate: Record<string, unknown> | null',
+      'projectOnboarding: Record<string, unknown> | null',
       '`sce project portfolio show --json`',
+      '`sce project candidate inspect --root <path> --json`',
+      '`sce project onboarding import --root <path> --json`',
       '`sce project target resolve --request <text> --current-project <project-id> --json`',
       '`sce project supervision show --project <project-id> --json`'
     ]
@@ -62,6 +70,8 @@ const REQUIRED_CHECKS = [
     path: 'docs/magicball-cli-invocation-examples.md',
     requiredSnippets: [
       'sce project portfolio show --json',
+      'sce project candidate inspect --root "C:/workspace/customer-order-demo" --json',
+      'sce project onboarding import --root "C:/workspace/customer-order-demo" --json',
       'sce project target resolve --request "continue customer-order-demo" --json',
       'sce project supervision show --project workspace:customer-order-demo --json'
     ]
@@ -71,6 +81,8 @@ const REQUIRED_CHECKS = [
     requiredSnippets: [
       '## Phase 0: Multi-project Workspace Shell',
       'sce project portfolio show --json',
+      'sce project candidate inspect --root "<path>" --json',
+      'sce project onboarding import --root "<path>" --json',
       'sce project target resolve --request "<text>" --current-project <project-id> --json',
       'sce project supervision show --project <project-id> --json'
     ]
@@ -80,14 +92,15 @@ const REQUIRED_CHECKS = [
     requiredSnippets: [
       '- `docs/magicball-project-portfolio-contract.md`',
       '- project switcher from `project portfolio show`',
+      '- local-root candidate receipt from `project candidate inspect`',
       '- project health summary from `project supervision show`'
     ]
   },
   {
     path: 'docs/magicball-integration-issue-tracker.md',
     requiredSnippets: [
-      '- `project portfolio show/target resolve/supervision show`',
-      '5. treat `project portfolio / target resolve / supervision` as the default multi-project shell truth'
+      '- `project portfolio show/candidate inspect/onboarding import/target resolve/supervision show`',
+      '5. treat `project portfolio / candidate inspect / onboarding import / target resolve / supervision` as the default multi-project shell truth'
     ]
   },
   {

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.60  
-**Last Updated**: 2026-03-19  
+**sce Version**: 3.6.61  
+**Last Updated**: 2026-03-20
 **Purpose**: Guide AI tools to work effectively with this project