scene-capability-engine 3.6.64 → 3.6.67

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.67
+**Last Updated**: 2026-03-29
 
 ---
 
@@ -52,11 +52,17 @@ sce doctor
 # Ensure an active scene primary session exists first
 sce studio plan --scene scene.customer-order-inventory --from-chat session-20260226 --goal "spec delivery cycle" --json
 
+# Or inherit scene/spec focus from an existing project channel
+sce studio plan --project-id project.customer-order --collab-channel channel-A --from-chat session-20260226 --goal "spec delivery cycle" --json
+
 # Legacy low-level: create spec directory only
 sce create-spec 01-00-feature-name
 
 # Bootstrap full Spec draft (requirements/design/tasks)
 sce spec bootstrap --name 01-00-feature-name --scene scene.customer-order-inventory --non-interactive
+
+# Or inherit the current scene from one project collaboration channel
+sce spec bootstrap --name 01-00-feature-name --project-id project.customer-order --collab-channel channel-A --non-interactive
 # Bootstrap now also generates mandatory scene artifacts:
 # - .sce/specs/<spec>/custom/problem-domain-map.md
 # - .sce/specs/<spec>/custom/scene-spec.md
@@ -65,9 +71,11 @@ sce spec bootstrap --name 01-00-feature-name --scene scene.customer-order-invent
 
 # Run pipeline for one Spec
 sce spec pipeline run --spec 01-00-feature-name --scene scene.customer-order-inventory
+sce spec pipeline run --spec 01-00-feature-name --project-id project.customer-order --collab-channel channel-A
 
 # Run gate for one Spec
 sce spec gate run --spec 01-00-feature-name --scene scene.customer-order-inventory --json
+sce spec gate run --spec 01-00-feature-name --project-id project.customer-order --collab-channel channel-A --json
 
 # Maintain domain modeling artifacts explicitly
 sce spec domain init --spec 01-00-feature-name --scene scene.customer-order-inventory --json
@@ -97,7 +105,9 @@ sce status --verbose
 ```
 
 Spec session governance:
-- `spec bootstrap|pipeline run|gate run` must bind to an active scene primary session (`--scene <scene-id>` or implicit binding from latest/unique active scene).
+- `spec bootstrap|pipeline run|gate run` must bind to an active scene primary session.
+- Recommended binding order is: `--scene <scene-id>` first, otherwise `--project-id <project-id> --collab-channel <channel-id>`, otherwise the legacy latest/unique active scene fallback.
+- When `--project-id + --collab-channel` is provided, sce treats that channel as the formal scene recovery source and will not fall back to unrelated latest studio job or global active-scene guessing.
 - When multiple active scenes exist, you must pass `--scene` explicitly.
 - Multi-Spec orchestrate fallback (`--specs ...`) follows the same scene binding and writes per-spec child-session archive records.
 - `sce spec strategy assess` is read-only and should be used when you are not sure whether the current problem still fits one Spec.
@@ -209,6 +219,8 @@ sce task show --ref <SS.PP.TT> --json
 sce task rerun --ref <SS.PP.TT> --dry-run --json
 ```
 
+When the referenced task comes from a studio stage, `task show/rerun --json` also returns `project_channel.active_scene + active_spec_id`, so rerun hints stay aligned with the original channel focus.
+
 Task references and studio runtime events are persisted in SQLite state store:
 - `.sce/state/sce-state.sqlite`
 - Backend policy: SQLite only (no file-backend mode).
@@ -263,6 +275,7 @@ sce steering compile --tool claude --agent-version 0.9.0
 
 # Start/resume/snapshot cross-agent runtime sessions
 sce session start "ship order workflow hardening" --tool codex --agent-version 1.2.3 --id release-20260224
+sce session start "ship order workflow hardening" --tool codex --project-id project.customer-order --channel channel-A --scene scene.customer-order --spec 142-00-project-channel-session-parallel-collaboration-contract --json
 sce session resume release-20260224 --status active
 sce session snapshot release-20260224 --summary "post-gate checkpoint" --payload '{"tests_passed":42}' --json
 sce session show release-20260224 --json
@@ -271,11 +284,12 @@ sce session list --limit 20 --json
 
 Session governance defaults:
 - `1 scene = 1 primary session` (managed by `studio plan --scene ...`)
-- `spec` runs can bind as child sessions (`spec bootstrap|pipeline --scene <scene-id>`)
+- `spec` runs can bind as child sessions (`spec bootstrap|pipeline|gate --scene <scene-id>` or `--project-id <project-id> --collab-channel <channel-id>`)
 - successful `studio release` auto-archives current scene session and opens next cycle session
 - `session show/list` JSON now includes runtime diagnostics:
   - `session_source`
   - `scene_index.status` (`aligned`, `pending-sync`, `sqlite-ahead`, etc.)
+  - when project/channel binding is requested, `project_channel.active_scene + active_spec_id + active_doc + resolved_session_id`
 
 ### Watch Mode
 
@@ -782,7 +796,9 @@ Studio JSON output now includes a stable UI-oriented task stream contract (in ad
   - `sce task rerun --ref <SS.PP.TT> [--dry-run] --json`
 
 Stage guardrails are enforced by default:
-- `plan` requires `--scene`; SCE binds one active primary session per scene
+- `plan` accepts explicit `--scene`, or inherits `active_scene` from the resolved `project + channel` context
+- explicit `--spec` always wins; channel-saved `activeSpecId` is only treated as a candidate binding and never as an implicit override
+- `project_channel` projections in `session/studio/task/native` JSON payloads preserve both `active_scene` and `active_spec_id`
 - `plan` runs auto intake by default (`.sce/config/studio-intake-policy.json`):
   - detect goal intent (`change_request` vs `analysis_only`)
   - resolve spec via explicit binding / scene latest / related specs / auto-create
@@ -791,6 +807,7 @@ Stage guardrails are enforced by default:
 - `plan --no-spec-governance` is blocked by default (`governance.require_auto_on_plan=true`)
 - `plan --spec <id>` (recommended) ingests `.sce/specs/<spec>/custom/problem-domain-chain.json` into studio job context
 - when `--spec` is omitted, `plan` auto-resolves the latest matching spec chain by `scene_id` when available
+- when `--scene` is omitted but `--project-id + --collab-channel` can resolve one channel focus, `plan/intake` inherit that channel's `active_scene`
 - `plan` auto-searches related historical specs by `scene + goal` and writes top candidates into job metadata (`source.related_specs`)
 - `plan` auto-runs scene spec governance snapshot and writes:
   - `.sce/spec-governance/scene-portfolio.latest.json`
@@ -806,6 +823,24 @@ Stage guardrails are enforced by default:
 - `release` requires `verify`
 - `verify` / `release` reports and failure auto-records inherit `spec_id + domain-chain` context for better root-cause traceability
 
+Supreme-intent governance defaults:
+- `studio plan` / `studio intake` first pass through the Four Teachings supreme-intent gate before scene/spec routing or job activation.
+- Possible governance actions are `allow`, `clarify`, `rewrite`, `narrow`, and `refuse`.
+- `clarify` stops execution and returns clarification questions; `rewrite` / `narrow` continue with an effective governed goal; `refuse` blocks plan execution and returns a governed denial.
+- Supreme policy file: `.sce/config/supreme-principles-policy.json`
+- When a bound spec already exists, the assessment is written to `.sce/specs/<spec>/custom/supreme-intent-assessment.json`.
+- `studio plan` persists both `goal_original` and the governed `effective_goal` so downstream stages can audit how the goal was transformed.
+
+Native semantic runtime:
+- Start a native session with `sce native start --objective "<goal>" --project-id <project> --channel-id <channel> --scene <scene> [--spec <spec>] --json`
+- Run one governed native turn with `sce native ask "<prompt>" --session-id <session> --project-id <project> --channel-id <channel> --scene <scene> [--spec <spec>] --json`
+- `native ask` also passes through the same supreme-intent gate before semantic activation.
+- `clarify` and `refuse` return a governed reply without activating promoted behaviors.
+- `rewrite` and `narrow` activate the semantic runtime with the governed `effective_text` instead of the raw prompt.
+- native preload/activation now defaults to the current `project + channel + scene + spec` scope so sibling channels in the same project do not silently share active behaviors.
+- JSON output includes `supreme_principles`, and spec-scoped evidence is attached when the bound spec already exists.
+- The same assessment is also written into the SQLite/state supreme-intent ledger so later progress and backflow analysis can query it without scraping session payloads.
+
 Problem evaluation mode (default required):
 - Studio now runs problem evaluation on every stage: `plan`, `generate`, `apply`, `verify`, `release`.
 - Default policy file: `.sce/config/problem-eval-policy.json` (also provisioned by template/adopt/takeover baseline).
@@ -1869,6 +1904,11 @@ Clarification-first baseline audit helper:
   - Default behavior: audit current project root.
   - `--fail-on-violation` exits with code `2` when required clarification-first baselines drift or prohibited legacy phrases are detected.
 
+Agent-governance baseline audit helper:
+- `node scripts/agent-governance-baseline-audit.js [--project-path <path>] [--out <path>] [--fail-on-violation] [--json]`: verify that the supreme-principle steering baseline, spec-scoped artifact rules, multi-channel `CURRENT_CONTEXT`, supreme runtime policy/config, and `studio/native` Four Teachings gate hooks are all still present.
+  - Default behavior: audit current project root.
+  - `--fail-on-violation` exits with code `2` when governance baseline drift or missing runtime gate snippets are detected.
+
 Interactive change-plan generator helper (script-level stage-B planning bridge):
 - `node scripts/interactive-plan-build.js --intent <path> [--context <path>] [--execution-mode <suggestion|apply>] [--out-plan <path>] [--out-markdown <path>] [--json]`: generate structured `Change_Plan` from `Change_Intent`, including action candidates, risk level, verification checks, rollback plan, approval status, and gate hint command.
   - Default outputs:
@@ -2676,6 +2716,9 @@ sce project portfolio show [options]
 - Reuses registered workspace visibility from multi-workspace state
 - Marks inaccessible or partial projects explicitly instead of dropping them
 - Reuses project-local session governance signals to summarize active sessions and last activity
+- Returns `semanticSharedSources` summary on each project record so adapters can see approved/connected/pending shared-source state without scanning specs
+- Returns `projectChannelContext` summary on each project record so adapters can see focused channel, multi-channel counts, and `storageMode` without collapsing the project to one current thread
+- Returns `supervisionSignals` summary on each project record so operators can compare highest severity, actionable pressure, and the primary drillback command before entering a project
 
 #### `sce project candidate inspect`
 
@@ -2710,8 +2753,11 @@ 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
+- Returns `semanticSharedSourceDiscovery` in successful JSON payloads so adapters can consume approved shared-source hints without a second scan
+- Returns `projectChannelContext` (and focused `projectChannel` when present) in successful JSON payloads so adapters can preserve existing channel scene/spec state after import, including whether the recovered context came from `split` or legacy storage
+- 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`
 
@@ -2725,6 +2771,7 @@ sce project target resolve [options]
 **Options:**
 - `--request <text>` - Routing request text
 - `--current-project <id>` - Caller asserted current project id
+- `--channel <channel-id>` - Caller asserted current project channel id
 - `--workspace <name>` - Resolve caller context against one registered workspace
 - `--device <id>` - Opaque caller device id
 - `--tool-instance-id <id>` - Opaque caller tool instance id
@@ -2733,11 +2780,12 @@ sce project target resolve [options]
 **Behavior:**
 - Returns `current-project`, `resolved-other-project`, `ambiguous`, or `unresolved`
 - Echoes caller context used during resolution
+- Returns caller project-channel focus when the current project has recoverable project-channel context available, including `context_available`, `storage_mode`, and `requested_channel_id`
 - Returns alternative candidates for ambiguous matches
 
 #### `sce project supervision show`
 
-Inspect one project-scoped supervision snapshot with blocked, handoff, risk, and active items.
+Inspect one project-scoped supervision snapshot with blocked, handoff, risk, active, archive-accumulation, governance-hotspot, and semantic-backflow items.
 
 **Usage:**
 ```bash
@@ -2746,16 +2794,345 @@ sce project supervision show --project <id> [options]
 
 **Options:**
 - `--project <id>` - Visible project id from the portfolio projection
+- `--channel <channel-id>` - Resolve one project-channel focus without overwriting sibling channels
 - `--cursor <cursor>` - Best-effort checkpoint input; phase-1 still returns a full snapshot
 - `--json` - Output the canonical `ProjectSupervisionProjection`
 
 **Behavior:**
 - Reuses project-local session governance, spec governance, and report artifacts
 - Preserves scene/spec/event drillback fields when evidence is available
+- Adds item-level control-plane fields: `severity`, `blocking_scope`, `recommended_action`, and `recommended_command`
+- Returns `actionQueue` sorted by severity and recency, plus project-level `highestSeverity`, `actionableCount`, severity bucket counts, and `primaryRecommendedCommand`
+- Summarizes semantic archive accumulation from the local ledger so operators can see how project training value is settling into experience, ontology-capability, and application assets
+- Summarizes project-scoped supreme-intent governance pressure from the SQLite/state ledger, including rewrite/refuse counts and top channel/spec hotspots
+- Summarizes semantic backflow pressure from local `publish_blocked` lessons and central merge/release receipts, including blocked spec count and recent blocker items
+- Surfaces `info` items when approved semantic shared source descriptors are available but not yet connected
+- Returns `projectChannelContext` plus one resolved `projectChannel` focus when recoverable project-channel context is available, and now exposes `storageMode` / `storage_mode` so adapters can distinguish formal split storage from legacy compat reads
 - Returns an opaque snapshot cursor for polling without pretending to expose a raw event stream
 
 ---
 
+## Semantic Kernel
+
+#### `sce semantic observe`
+
+Record one vendor-neutral semantic observation from an embedded or native runtime.
+
+**Usage:**
+```bash
+sce semantic observe --runtime codex-cli --event reply --role assistant --project-id <project> --channel-id <channel> --session-id <session> --scene <scene> --spec <spec> --text "<summary>" --json
+```
+
+**Behavior:**
+- Normalizes embedded-host interaction into one SCE-owned semantic observation envelope
+- Preserves `project/channel/session/scene/spec/task` context when supplied
+- Distills a lesson candidate immediately when the observation carries enough signal
+
+#### `sce semantic replay`
+
+Build a replay dataset from recorded semantic observations.
+
+**Usage:**
+```bash
+sce semantic replay --project-id <project> --session-id <session> --spec <spec> --json
+```
+
+**Behavior:**
+- Restores project-aware semantic observations into one replay dataset
+- Keeps scene/spec/session provenance for later evaluation and promotion evidence
+
+#### `sce semantic eval`
+
+Evaluate a candidate reply or plan against recorded observations.
+
+**Usage:**
+```bash
+sce semantic eval --project-id <project> --spec <spec> --lesson-id <lesson-id> --candidate-reply "<reply>" --threshold 60 --json
+```
+
+**Behavior:**
+- Scores helpfulness, correctness, actionability, governance fit, and regression drift
+- Produces machine-readable evaluation evidence for promotion, quarantine, or rollback
+
+#### `sce semantic promote` / `sce semantic rollback`
+
+Promote or roll back a semantic lesson candidate.
+
+**Usage:**
+```bash
+sce semantic promote --lesson-id <lesson-id> --eval-run-id <evaluation-run-id> --json
+sce semantic rollback --lesson-id <lesson-id> --reason "<reason>" --json
+```
+
+**Behavior:**
+- Promotion writes capability-ledger lineage and, by default, immediately auto-publishes qualified deltas into the shared-library mirror under the adopt-implied model
+- Promotion/update also recalculates capability rank using recent supreme-intent pressure from the same project/channel/scene/spec scope
+- When the governed publication gate blocks shared publication, promotion still succeeds locally but the lesson/ledger move to `publish_blocked` instead of entering the shared library
+- Rollback deprecates the lesson and updates local capability state for future activation decisions
+
+#### `sce semantic progress`
+
+Summarize semantic learning, promotion, publication, and native backflow progress.
+
+**Usage:**
+```bash
+sce semantic progress --project-id <project> --spec <spec> --json
+```
+
+**Behavior:**
+- Reports the semantic funnel: observations, lessons, evaluation runs, promotions, and native activation
+- Reports publication state: `publish_pending`, `published-shared`, and `publish_blocked`
+- Reports archive accumulation summary so operators can see how training value is settling into experience, ontology-capability, and application assets
+- Reports approved-but-not-connected shared source descriptors so semantic intake pressure is visible in the same snapshot
+- Reports capability-ledger and native-hit signals for operator review, including how many promoted capabilities are currently governance-penalized/high-risk
+- Reports supreme-intent ledger counts (`allow|clarify|rewrite|narrow|refuse`) plus governed-action rate across the filtered scope
+- Returns operator control-plane fields (`operator_items`, `action_queue`, `operator_control_plane`) so semantic progress is no longer a progress-only snapshot
+
+#### `sce semantic archive-report`
+
+Summarize how project training value is routed and accumulated across the three semantic libraries.
+
+**Usage:**
+```bash
+sce semantic archive-report --project-id <project> --spec <spec> --recent-limit 10 --json
+```
+
+**Behavior:**
+- Aggregates lesson + capability-ledger state by `experience-library`, `ontology-capability-library`, and `application-library`
+- Returns archive-class and reuse-scope summaries so operators can distinguish experience accumulation from core capability growth and project application sediment
+- Returns recent archived items plus `missing_archive_count` so routing drift can be detected without manually reading lesson, ledger, and shared entry files
+
+#### `sce semantic supreme-intent`
+
+List supreme-intent governance assessments from the SQLite/state ledger.
+
+**Usage:**
+```bash
+sce semantic supreme-intent --project-id <project> --spec <spec> --source-kind studio-plan --action rewrite --json
+```
+
+**Behavior:**
+- Reads governed Four Teachings assessments from the SQLite/state ledger instead of scraping session payloads
+- Supports filtering by `project/channel/session/scene/spec/job/source-kind/action`
+- Returns the newest assessments first so operator review can inspect recent rewrites/refusals quickly
+
+#### `sce semantic supreme-intent-show`
+
+Show one supreme-intent governance assessment in full detail.
+
+**Usage:**
+```bash
+sce semantic supreme-intent-show <assessment-id> --json
+```
+
+**Behavior:**
+- Returns the full assessment payload, including worldview/lifeview/values/methodology fields, matched rules, evidence path, and metadata
+
+#### `sce semantic governance-report`
+
+Summarize supreme-intent governance hotspots from the SQLite/state ledger.
+
+**Usage:**
+```bash
+sce semantic governance-report --project-id <project> --hotspot-limit 5 --recent-limit 10 --json
+```
+
+**Behavior:**
+- Aggregates recent Four Teachings assessments into operator-facing hotspots instead of returning only raw rows
+- Reports totals, governed-action rate, planning/execution blocked counts, top projects/channels/specs, and top project+channel+scene+spec hotspots
+- Extracts repeated matched-rule ids and recent `rewrite` / `refuse` items so training backflow, capability rerank, and governance tuning can converge faster
+
+#### `sce semantic backflow-report`
+
+Summarize local and central backflow blockers across semantic publication and registry gates.
+
+**Usage:**
+```bash
+sce semantic backflow-report --project-id <project> --spec <spec> --recent-limit 10 --json
+```
+
+**Behavior:**
+- Aggregates local `publish_blocked` lessons plus the latest central merge/release receipts under the filtered specs
+- Separates blockers by stage: local publish gate, central merge gate, and approved-central release gate
+- Returns `blocked_spec_count` / `blocked_spec_ids` so project supervision and operator consoles can distinguish isolated failures from spec-wide stalled backflow
+- Returns grouped blocker reasons and recent blocked items/receipts so operators can see where capability flow is stalling without manually reading multiple receipts
+
+#### `sce semantic export-delta`
+
+Export governed `publish_pending` semantic deltas for shared-library publication.
+
+**Usage:**
+```bash
+sce semantic export-delta --project-id <project> --spec <spec> --json
+sce semantic export-delta --project-id <project> --spec <spec> --out-file .sce/specs/<spec>/deltas/latest.json --json
+```
+
+**Behavior:**
+- Exports sanitized delta entries instead of sharing the local SQLite database
+- Routes each entry toward exactly one of the experience, ontology-capability, or application libraries
+- Carries the normalized archive decision so downstream publication and operator reports preserve why the entry belongs to that library
+- When `--spec` is supplied and `--out-file` is omitted, writes to `.sce/specs/<spec>/deltas/latest.json` by default
+
+#### `sce semantic publish-delta`
+
+Publish governed semantic deltas into the local shared-library mirror and advance publish state.
+
+**Usage:**
+```bash
+sce semantic publish-delta --project-id <project> --spec <spec> --json
+sce semantic publish-delta --input-file .sce/specs/<spec>/deltas/latest.json --out-file .sce/specs/<spec>/publications/semantic/latest.json --json
+```
+
+**Behavior:**
+- Accepts an existing delta manifest or exports `publish_pending` entries first when `--input-file` is omitted
+- Writes shared-library mirror entries under `.sce/knowledge/semantic-shared/<library>/entries/`
+- Preserves project/channel/session/scene/spec provenance plus archive routing inside the published shared entry payload
+- Updates lesson/ledger publication state to `published-shared` and emits a machine-readable publication report
+- Applies the governed publication gate before shared write: entries with `refuse` / `execution_blocked` history or excessive governance penalty stay local and are marked `publish_blocked`
+- Keeps SQLite as local ledger only; the publish contract shares structured delta entries, not the database file
+
+#### `sce semantic export-shared-sync`
+
+Export the local semantic shared-library mirror into a governed sync handoff bundle.
+
+**Usage:**
+```bash
+sce semantic export-shared-sync --project-id <project> --spec <spec> --json
+sce semantic export-shared-sync --project-id <project> --spec <spec> --capability-id <capability> --json
+sce semantic export-shared-sync --project-id <project> --spec <spec> --out-file .sce/specs/<spec>/sync/semantic-shared/latest.bundle.json --json
+```
+
+**Behavior:**
+- Reads governed entries from `.sce/knowledge/semantic-shared/`, not from SQLite
+- Emits a spec-scoped bundle, index, receipt, and per-library shard files under `.sce/specs/<spec>/sync/semantic-shared/` by default
+- Carries forward project/channel/session/scene/spec provenance from the shared mirror into the handoff shards
+- Supports filtering by `project/spec/lesson/capability/library`
+- Produces a machine-readable handoff summary for future shared-truth or upstream intake flows
+
+#### `sce semantic sync-shared`
+
+Sync a governed semantic shared-sync bundle from an approved source into the local shared mirror.
+
+**Usage:**
+```bash
+sce semantic sync-shared --source /path/to/latest.bundle.json --spec <spec> --json
+sce semantic sync-shared --source https://example.com/.sce/specs/<spec>/sync/semantic-shared/latest.bundle.json --source-root https://example.com --spec <spec> --json
+sce semantic sync-shared --source-name central --required-release-state approved-central --config .sce/config/semantic-shared-sources.json --spec <spec> --json
+```
+
+**Behavior:**
+- Reads shared-sync bundle + shard payloads from local file or `http(s)` source
+- Intakes valid entries into `.sce/knowledge/semantic-shared/` while preserving `project/channel/session/scene/spec` provenance
+- Can require a configured or explicit source to be in a specific governance release state such as `approved-central`
+- Skips stale or duplicate entries instead of blindly overwriting newer local mirror content
+- Blocks intake before shard import when the bundle release state does not satisfy the configured requirement
+- Writes a machine-readable intake receipt to `.sce/specs/<spec>/intake/semantic-shared/latest.json` by default when `--spec` is supplied
+
+#### `sce semantic health-shared-source`
+
+Validate one configured or explicit semantic shared-sync source before intake.
+
+**Usage:**
+```bash
+sce semantic health-shared-source --source /path/to/latest.bundle.json --json
+sce semantic health-shared-source --source-name central --config .sce/config/semantic-shared-sources.json --json
+sce semantic health-shared-source --source-name central --required-release-state approved-central --config .sce/config/semantic-shared-sources.json --json
+```
+
+**Behavior:**
+- Loads the bundle without writing to the local mirror
+- Verifies shard resolution and shard payload health
+- Reports bundle release-state compliance when a required release-state policy is configured or explicitly requested
+- Reports warnings/errors separately, plus shard counts and total entry count
+
+#### `sce semantic list-shared-sources`
+
+List configured semantic shared sources from `.sce/config/semantic-shared-sources.json`.
+
+**Usage:**
+```bash
+sce semantic list-shared-sources --json
+sce semantic list-shared-sources --config .sce/config/semantic-shared-sources.json --json
+```
+
+**Behavior:**
+- Reads the project semantic shared source config
+- Emits the configured sources sorted by name
+- Surfaces `bundle`, `enabled`, and `required_release_state` for operator review
+
+#### `sce semantic set-shared-source`
+
+Upsert one semantic shared source into `.sce/config/semantic-shared-sources.json`.
+
+**Usage:**
+```bash
+sce semantic set-shared-source --name central --bundle https://example.com/.sce/specs/143-13/registry/semantic-shared/published/latest.bundle.json --root https://example.com --required-release-state approved-central --json
+sce semantic set-shared-source --name backup --bundle /path/to/latest.bundle.json --enabled false --json
+sce semantic set-shared-source --input-file .sce/specs/<spec>/registry/semantic-shared/published/source-descriptor.json --json
+```
+
+**Behavior:**
+- Creates the semantic shared source config when it does not exist yet
+- Upserts one named source instead of duplicating entries
+- Can read a governed source descriptor and then apply explicit CLI overrides on top
+- Persists optional `root`, `enabled`, and `required_release_state` alongside the bundle reference
+
+#### `sce semantic connect-shared-source`
+
+Consume one approved source descriptor, register it, run health gate, and sync it into the local mirror.
+
+**Usage:**
+```bash
+sce semantic connect-shared-source --input-file .sce/specs/<spec>/registry/semantic-shared/published/source-descriptor.json --json
+sce semantic connect-shared-source --spec <spec> --json
+sce semantic connect-shared-source --input-file /path/to/source-descriptor.json --no-sync-now --json
+```
+
+**Behavior:**
+- Reads a governed source descriptor and rejects non-`approved-central` descriptors by default
+- Upserts the source config before running health and sync
+- Runs `health-shared-source` and then `sync-shared` in one governed flow unless explicitly disabled
+- Keeps `--allow-non-approved` as an explicit escape hatch instead of silently relaxing governance
+
+#### `sce semantic merge-shared`
+
+Merge multiple governed semantic shared-sync bundles into one central/shared-truth candidate bundle.
+
+**Usage:**
+```bash
+sce semantic merge-shared --source /path/to/bundle-a.json --source /path/to/bundle-b.json --spec <spec> --json
+sce semantic merge-shared --sources /path/to/a.json,/path/to/b.json --spec <spec> --json
+```
+
+**Behavior:**
+- Reads multiple governed bundle sources and their shard payloads
+- Applies a central merge gate before deduplication: entries whose `publication.publish_state` is not `published-shared`, or that already carry blocked governance metadata, are rejected instead of entering the candidate bundle
+- Deduplicates by `target_library + capability_id`, keeping the latest `published_at`
+- Emits one merged bundle/index/receipt/shard set under `.sce/specs/<spec>/registry/semantic-shared/` by default
+- Records superseded duplicates in the merge receipt for governance review
+
+#### `sce semantic publish-shared-registry`
+
+Promote one merged semantic shared candidate bundle into the approved central registry after release gates pass.
+
+**Usage:**
+```bash
+sce semantic publish-shared-registry --spec <spec> --json
+sce semantic publish-shared-registry --spec <spec> --min-sources 2 --min-entries 10 --json
+sce semantic publish-shared-registry --input-file .sce/specs/<spec>/registry/semantic-shared/latest.bundle.json --out-file .sce/specs/<spec>/registry/semantic-shared/published/latest.bundle.json --json
+sce semantic publish-shared-registry --spec <spec> --source-name central --public-bundle https://example.com/.sce/specs/<spec>/registry/semantic-shared/published/latest.bundle.json --public-root https://example.com --json
+```
+
+**Behavior:**
+- Reads the merged candidate bundle produced by `sce semantic merge-shared`
+- Applies release gates for minimum source count, minimum merged entry count, and optional zero-blocked enforcement
+- Re-checks candidate shard entries before approval so non-`published-shared` or already-blocked entries cannot bypass governance by skipping merge-time validation
+- Emits one approved bundle/index/receipt/shard set under `.sce/specs/<spec>/registry/semantic-shared/published/` by default
+- Emits a governed `source-descriptor.json` alongside the approved bundle so downstream terminals can register the source without retyping parameters
+- Marks the result as `approved-central` or `publish-blocked` without writing SQLite or local terminal mirrors
+
+---
+
 ## See Also
 
 - [Multi-Repository Management Guide](./multi-repo-management-guide.md)

package/docs/document-governance.md

@@ -21,8 +21,8 @@ Document governance ensures your project follows these rules:
 
 1. **Root Directory** - Only 4 markdown files allowed: `README.md`, `README.zh.md`, `CHANGELOG.md`, `CONTRIBUTING.md`
 2. **Spec Structure** - Each Spec must have `requirements.md`, `design.md`, `tasks.md`
-3. **Artifact Organization** - Spec artifacts must be in subdirectories, except approved Spec-root metadata such as `requirements.md`, `design.md`, `tasks.md`, and `collaboration.json`
-4. **No Temporary Files** - Temporary documents (like `*-SUMMARY.md`, `SESSION-*.md`) must be deleted after use
+3. **Artifact Organization** - Agent-generated artifacts, debug logs, test scripts, reports, and analysis notes must stay in the active Spec subdirectories, except approved Spec-root metadata such as `requirements.md`, `design.md`, `tasks.md`, and `collaboration.json`
+4. **No Temporary Files** - Temporary documents (like `*-SUMMARY.md`, `SESSION-*.md`) must live under the active Spec while in use and must be deleted after use
 
 ### Why Use Document Governance?
 
@@ -31,6 +31,7 @@ Document governance ensures your project follows these rules:
 - ✅ **Automate Cleanup** - Remove temporary files automatically
 - ✅ **Prevent Violations** - Git hooks block non-compliant commits
 - ✅ **Track Compliance** - Statistics and reports over time
+- ✅ **Keep Agent Output Scoped** - Prevent debug logs, notes, and helper scripts from spreading outside the active Spec
 
 ---