phasegate 0.222.0 → 0.254.0

package/docs/contracts/world-obligation-report.schema.json

@@ -0,0 +1,259 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://phasegate.dev/contracts/world-obligation-report.schema.json",
+  "title": "PhaseGate World obligation report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "evaluationId",
+    "rulesetVersion",
+    "policyInputsDigest",
+    "structuralObligations",
+    "repaidBaselineEntries",
+    "declaredSemanticDebts",
+    "policyDiagnostics",
+    "summary"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "phasegate-world-obligation-report/v1" },
+    "evaluationId": {
+      "type": "string",
+      "pattern": "^pgw:v1:evaluation:sha256:[0-9a-f]{64}$"
+    },
+    "rulesetVersion": { "type": "string", "minLength": 1 },
+    "policyInputsDigest": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "structuralObligations": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/structuralObligation" }
+    },
+    "repaidBaselineEntries": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/repaidBaselineEntry" }
+    },
+    "declaredSemanticDebts": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/semanticDebt" }
+    },
+    "policyDiagnostics": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/policyDiagnostic" }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "structuralObligations",
+        "repaidBaselineEntries",
+        "declaredSemanticDebts",
+        "policyDiagnostics"
+      ],
+      "properties": {
+        "structuralObligations": { "type": "integer", "minimum": 0 },
+        "repaidBaselineEntries": { "type": "integer", "minimum": 0 },
+        "declaredSemanticDebts": { "type": "integer", "minimum": 0 },
+        "policyDiagnostics": { "type": "integer", "minimum": 0 }
+      }
+    }
+  },
+  "$defs": {
+    "jsonValue": {
+      "oneOf": [
+        { "type": "null" },
+        { "type": "boolean" },
+        { "type": "number" },
+        { "type": "string" },
+        {
+          "type": "array",
+          "items": { "$ref": "#/$defs/jsonValue" }
+        },
+        {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/jsonValue" }
+        }
+      ]
+    },
+    "pin": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["nodeId", "contentDigest"],
+          "properties": {
+            "nodeId": { "type": "string", "pattern": "^pgw:v1:.+" },
+            "contentDigest": {
+              "type": "string",
+              "pattern": "^sha256:[0-9a-f]{64}$"
+            }
+          }
+        }
+      ]
+    },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["endpointRole", "nodeIds"],
+      "properties": {
+        "endpointRole": {
+          "enum": ["claimant", "premise", "both", "declaration", "global"]
+        },
+        "nodeIds": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^pgw:v1:.+" }
+        }
+      }
+    },
+    "waiver": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["waiverId", "reason", "expiresOn", "workItemId"],
+          "properties": {
+            "waiverId": { "type": "string", "pattern": "^pgw:v1:waiver:.+" },
+            "reason": { "type": "string", "minLength": 1 },
+            "expiresOn": {
+              "type": "string",
+              "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
+            },
+            "workItemId": { "type": "string", "pattern": "^WI-[0-9]+$" }
+          }
+        }
+      ]
+    },
+    "structuralObligation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "violationFingerprint",
+        "ruleId",
+        "constraintId",
+        "factType",
+        "subject",
+        "claimantPin",
+        "premisePin",
+        "expected",
+        "observed",
+        "classification",
+        "waiver"
+      ],
+      "properties": {
+        "violationFingerprint": {
+          "type": "string",
+          "pattern": "^pgw:v1:violation-fingerprint:sha256:[0-9a-f]{64}$"
+        },
+        "ruleId": { "type": "string", "pattern": "^WCR-[0-9]{3}$" },
+        "constraintId": {
+          "oneOf": [
+            { "type": "null" },
+            { "type": "string", "pattern": "^pgw:v1:constraint:.+" }
+          ]
+        },
+        "factType": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "enum": ["references", "depends-on", "refines", "content-equals"]
+            }
+          ]
+        },
+        "subject": { "$ref": "#/$defs/subject" },
+        "claimantPin": { "$ref": "#/$defs/pin" },
+        "premisePin": { "$ref": "#/$defs/pin" },
+        "expected": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/jsonValue" }
+        },
+        "observed": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/jsonValue" }
+        },
+        "classification": {
+          "enum": [
+            "adopted-legacy",
+            "new-structural",
+            "invalid-declaration",
+            "waived"
+          ]
+        },
+        "waiver": { "$ref": "#/$defs/waiver" }
+      }
+    },
+    "repaidBaselineEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "violationFingerprint",
+        "ruleId",
+        "constraintId",
+        "classification",
+        "disposition"
+      ],
+      "properties": {
+        "violationFingerprint": {
+          "type": "string",
+          "pattern": "^pgw:v1:violation-fingerprint:sha256:[0-9a-f]{64}$"
+        },
+        "ruleId": { "type": "string", "pattern": "^WCR-[0-9]{3}$" },
+        "constraintId": {
+          "oneOf": [
+            { "type": "null" },
+            { "type": "string", "pattern": "^pgw:v1:constraint:.+" }
+          ]
+        },
+        "classification": { "const": "repaid" },
+        "disposition": { "const": "cleanup-required" }
+      }
+    },
+    "semanticDebt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "schemaVersion",
+        "debtId",
+        "kind",
+        "title",
+        "reason",
+        "ownerUnit",
+        "introducedByWorkItemId",
+        "references"
+      ],
+      "properties": {
+        "schemaVersion": { "const": "phasegate-world-debts/v1" },
+        "debtId": { "type": "string", "pattern": "^pgw:v1:semantic-debt:.+" },
+        "kind": { "const": "semantic" },
+        "title": { "type": "string", "minLength": 1 },
+        "reason": { "type": "string", "minLength": 1 },
+        "ownerUnit": { "type": "string", "minLength": 1 },
+        "introducedByWorkItemId": {
+          "type": "string",
+          "pattern": "^WI-[0-9]+$"
+        },
+        "references": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^pgw:v1:.+" }
+        }
+      }
+    },
+    "policyDiagnostic": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "subjectId", "details"],
+      "properties": {
+        "code": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+        "subjectId": {
+          "oneOf": [{ "type": "null" }, { "type": "string", "minLength": 1 }]
+        },
+        "details": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/jsonValue" }
+        }
+      }
+    }
+  }
+}

package/docs/contracts/world-waivers.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://phasegate.dev/contracts/world-waivers.schema.json",
+  "title": "PhaseGate World waivers",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "waivers"],
+  "properties": {
+    "schemaVersion": { "const": "phasegate-world-waivers/v1" },
+    "waivers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["waiverId", "violationFingerprint", "reason", "expiresOn", "workItemId", "renewalOf"],
+        "properties": {
+          "waiverId": { "type": "string", "pattern": "^pgw:v1:waiver:[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$" },
+          "violationFingerprint": { "type": "string", "pattern": "^pgw:v1:violation-fingerprint:sha256:[0-9a-f]{64}$" },
+          "reason": { "type": "string", "minLength": 1 },
+          "expiresOn": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+          "workItemId": { "type": "string", "pattern": "^WI-[0-9]+$" },
+          "renewalOf": {
+            "oneOf": [
+              { "type": "null" },
+              { "type": "string", "pattern": "^pgw:v1:waiver:[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$" }
+            ]
+          }
+        }
+      }
+    }
+  }
+}

package/docs/guide/cli-reference.md

@@ -325,6 +325,40 @@ L4 warning findings fail the process only when warning strictness is enabled (`v
 
 ---
 
+## World Model
+
+<!-- @work-item-id WI-299 -->
+
+World Model コマンド（ADR-037）。設計文書・ソース・テスト・matrix・attestation を型付き事実グラフとして抽出し、pin された制約を両端点対称に再評価して義務を導出する。明示実行は config に依存せず常に可能（`world.enabled` は既定 `false` で、将来の L2/L3 ゲート統合のみを制御。validator ID `L2-017` / `L3-008` は予約済み・未登録）。
+
+| Command | Options | Description |
+|---|---|---|
+| `world:inspect` | `--format human\|json` `--json` | Read-only World snapshot（node / edge / 抽出 diagnostics）を構築・表示。宣言も report も書かない |
+| `world:pin` | `--constraint <id>`（`pgw:v1:constraint` ID, 必須） `--endpoint <claimant\|premise>`（必須） `--apply` `--format human\|json` `--json` | 制約端点の現在 digest をプレビュー。`--apply` で `phasegate.world-constraints.json` を atomic に更新 |
+| `world:derive` | `--write` `--out <path>`（`--write` 必須） `--format human\|json` `--json` | immutable な obligation report を再導出。既定は pure・read-only。`--write` で raw report を `.harness/world-obligations.json`（untracked）へ永続化 |
+
+### Exit code
+
+| Exit | 意味 |
+|---|---|
+| 0 | クリーン（`world:derive` では adopted-legacy / waived / declared debt のみで blocking なし） |
+| 1 | blocking な finding あり（`world:inspect` は抽出 diagnostics あり、`world:derive` は新規違反・期限切れ waiver 等） |
+| 2 | 契約エラー（未知の control-file schema、不正な引数など） |
+
+### 制御ファイルと出力
+
+| File | Role |
+|---|---|
+| `phasegate.world-constraints.json` | pin された制約宣言（`world:pin --apply` が更新する唯一の mutation 経路） |
+| `phasegate.world-baseline.json` | 既存違反の adoption baseline（閉じた集合・縮小のみ。同一 ruleset での追加は拒否） |
+| `phasegate.world-waivers.json` | 単一 fingerprint 単位の waiver（理由 / 期限 / Work Item 必須） |
+| `phasegate.world-debts.json` | 宣言済み semantic debt（import として表示され、「再発見」はしない） |
+| `.harness/world-obligations.json` | `world:derive --write` の永続 report。**導出結果のキャッシュに過ぎず**、手編集・削除しても再導出の判定は変わらない |
+
+JSON 出力は envelope `phasegate-world-cli/v1` に包まれ、同一 checkout での 2 回実行は byte-identical（決定性契約）。schema は `docs/contracts/world-*.schema.json` を参照。
+
+---
+
 ## ADR Management
 
 | Command | Options | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.222.0",
+  "version": "0.254.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",

package/scripts/harness/attestation/application/ports/sha256-capability.ts

@@ -0,0 +1,25 @@
+// @unit attestation
+// @layer application
+// @work-item-id WI-286
+
+/**
+ * Unit境界を越えて受け渡すplain SHA-256 digest。
+ *
+ * 64桁lowercase hexのruntime invariantはproviderと各consumer-local VOが検証する。
+ * attestation domainのDigestはこのpublic contractへ露出しない。
+ */
+export type Sha256DigestString = `sha256:${string}`;
+
+/**
+ * Raw bytesをSHA-256するattestation public capability。
+ */
+export interface Sha256Capability {
+  hashBytes(bytes: Uint8Array): Sha256DigestString;
+}
+
+/**
+ * Unicode normalizationを行わず、TextEncoderのUTF-8 bytesをpublic capabilityへ渡す。
+ */
+export function hashUtf8(capability: Sha256Capability, text: string): Sha256DigestString {
+  return capability.hashBytes(new TextEncoder().encode(text));
+}

package/scripts/harness/attestation/composition-root.ts

@@ -10,16 +10,18 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { AttestationRecordMapper } from "./application/mappers/attestation-record-mapper.js";
+import type { Sha256Capability } from "./application/ports/sha256-capability.js";
 import { ProduceAttestationUseCase } from "./application/usecases/produce-attestation-usecase.js";
 import { VerifyAttestationUseCase } from "./application/usecases/verify-attestation-usecase.js";
-import { GranularityDerivationService } from "./domain/services/granularity-derivation-service.js";
 import { AcBoundScopeService } from "./domain/services/ac-bound-scope-service.js";
+import { GranularityDerivationService } from "./domain/services/granularity-derivation-service.js";
 import { CiCheckGateResultAdapter } from "./infrastructure/adapters/ci-check-gate-result-adapter.js";
+import { ConfigAcBoundAllowlistAdapter } from "./infrastructure/adapters/config-ac-bound-allowlist-adapter.js";
 import { FileSystemAttestationRepositoryAdapter } from "./infrastructure/adapters/file-system-attestation-repository-adapter.js";
-import { FileSystemSourceDigesterAdapter } from "./infrastructure/adapters/file-system-source-digester-adapter.js";
 import { FileSystemMatrixSourceAdapter } from "./infrastructure/adapters/file-system-matrix-source-adapter.js";
-import { ConfigAcBoundAllowlistAdapter } from "./infrastructure/adapters/config-ac-bound-allowlist-adapter.js";
+import { FileSystemSourceDigesterAdapter } from "./infrastructure/adapters/file-system-source-digester-adapter.js";
 import { NodeCryptoContentHasherAdapter } from "./infrastructure/adapters/node-crypto-content-hasher-adapter.js";
+import { NodeCryptoSha256Capability } from "./infrastructure/adapters/node-crypto-sha256-capability.js";
 import { AttestHandler } from "./presentation/handlers/attest-handler.js";
 import { VerifyAttestationHandler } from "./presentation/handlers/verify-attestation-handler.js";
 
@@ -41,13 +43,21 @@ export interface AttestationModuleOptions {
   readonly clock?: () => Date;
 }
 
+/**
+ * Unit非依存のplain SHA-256 public capabilityを生成する。
+ */
+export function createSha256Capability(): Sha256Capability {
+  return new NodeCryptoSha256Capability();
+}
+
 /**
  * attestation Unit のモジュールを組み立てる。
  * @param rootDir プロジェクトルート（source digest / repository の baseDir）。
  */
 export function createAttestationModule(rootDir: string, options?: AttestationModuleOptions): AttestationModule {
   // Infrastructure adapters
-  const hasher = new NodeCryptoContentHasherAdapter();
+  const sha256Capability = createSha256Capability();
+  const hasher = new NodeCryptoContentHasherAdapter(sha256Capability);
   const sourceDigester = new FileSystemSourceDigesterAdapter(rootDir);
   const gateResultSource = new CiCheckGateResultAdapter({ mainTsPath: options?.mainTsPath });
   const repository = new FileSystemAttestationRepositoryAdapter(rootDir);

package/scripts/harness/attestation/index.ts

@@ -5,9 +5,14 @@
 // Public DTO types
 export type { AttestationDocument } from "./application/dto/attestation-document.js";
 export type { VerifyAttestationOutput } from "./application/dto/verify-attestation-output.js";
+export {
+  hashUtf8,
+  type Sha256Capability,
+  type Sha256DigestString,
+} from "./application/ports/sha256-capability.js";
 export type { AttestationModule, AttestationModuleOptions } from "./composition-root.js";
 // Composition Root
-export { createAttestationModule } from "./composition-root.js";
+export { createAttestationModule, createSha256Capability } from "./composition-root.js";
 export type { AttestHandlerArgs, AttestHandlerResult } from "./presentation/handlers/attest-handler.js";
 // Presentation Handlers
 export { AttestHandler } from "./presentation/handlers/attest-handler.js";

package/scripts/harness/attestation/infrastructure/adapters/node-crypto-content-hasher-adapter.ts

@@ -1,18 +1,18 @@
 // @unit attestation
 // @layer infrastructure
 
-import { createHash } from "node:crypto";
+import { hashUtf8, type Sha256Capability } from "../../application/ports/sha256-capability.js";
 import type { ContentHasherPort } from "../../domain/ports/content-hasher-port.js";
 import { Digest } from "../../domain/value-objects/digest.js";
+import { NodeCryptoSha256Capability } from "./node-crypto-sha256-capability.js";
 
 /**
- * ContentHasherPort の node:crypto 実装。
- * canonical payload / source content の sha256 を `sha256:<64hex>` Digest として返す。
- * installation の node-crypto-hash-adapter をミラーし、アルゴリズムは sha256 に固定する。
+ * Public Sha256Capabilityをattestation-local ContentHasherPortへ変換するadapter。
  */
 export class NodeCryptoContentHasherAdapter implements ContentHasherPort {
+  constructor(private readonly capability: Sha256Capability = new NodeCryptoSha256Capability()) {}
+
   sha256(content: string): Digest {
-    const hex = createHash("sha256").update(content, "utf8").digest("hex");
-    return Digest.fromSha256Hex(hex);
+    return Digest.create(hashUtf8(this.capability, content));
   }
 }

package/scripts/harness/attestation/infrastructure/adapters/node-crypto-sha256-capability.ts

@@ -0,0 +1,19 @@
+// @unit attestation
+// @layer infrastructure
+// @work-item-id WI-286
+
+import { createHash } from "node:crypto";
+import type { Sha256Capability, Sha256DigestString } from "../../application/ports/sha256-capability.js";
+
+/**
+ * Attestation public SHA-256 capabilityのNode.js実装。
+ *
+ * 既存NodeCryptoContentHasherAdapterからprimitiveを移動し、
+ * World向けにnode:crypto call siteを増やさない。
+ */
+export class NodeCryptoSha256Capability implements Sha256Capability {
+  hashBytes(bytes: Uint8Array): Sha256DigestString {
+    const hex = createHash("sha256").update(bytes).digest("hex");
+    return `sha256:${hex}`;
+  }
+}

package/scripts/harness/harness-api/domain/value-objects/known-harness-commands.ts

@@ -1,6 +1,6 @@
 // @unit harness-api
 // @layer domain
-// @work-item-id WI-250
+// @work-item-id WI-250, WI-291, WI-296
 // known-harness-commands.ts — CLI 実サーフェスの canonical 既知コマンド一覧
 //
 // main.ts の CLI dispatch（`switch (command)`）が受理する全トップレベルコマンド名の
@@ -87,4 +87,7 @@ export const KNOWN_HARNESS_COMMANDS: readonly string[] = Object.freeze([
   "validate-fix",
   "validate-metadata",
   "work-items:status",
+  "world:derive",
+  "world:inspect",
+  "world:pin",
 ]);

package/scripts/harness/main.ts

@@ -21,6 +21,7 @@
  * @work-item-id WI-213
  * @work-item-id WI-217
  * @work-item-id WI-219
+ * @work-item-id WI-291
  *
  * Phasegate CLI エントリポイント。
  * 各Unitの Composition Root からハンドラーを取得し、コマンドに応じてディスパッチする。
@@ -92,6 +93,12 @@ import {
 import { createSkillQualityHandlers } from "./skill-quality/composition-root.js";
 import { createTraceabilityModelModule } from "./traceability-model/composition-root.js";
 import { createValidatorSystemModule } from "./validator-system/composition-root.js";
+import {
+  createWorldModelModule,
+  WorldDeriveCommandHandler,
+  WorldInspectCommandHandler,
+  WorldPinCommandHandler,
+} from "./world-model/index.js";
 
 /**
  * main.ts (scripts/harness/main.ts) から2階層上がパッケージルート。
@@ -232,6 +239,9 @@ Commands:
   phasegate:generate-matrix      Generate requirement-test matrix (--requirements, --tests, --out, --json)
   phasegate:attest               Produce a signed-attestation record of ci-check (--out <path>, --require-pass, --mode <unsigned-poc|signed>, --json)
   phasegate:verify-attestation   Verify an attestation record's integrity (<file>, --json)
+  world:inspect                  Inspect the read-only World snapshot (--format human|json, --json)
+  world:pin                      Preview or apply an endpoint pin (--constraint, --endpoint, --apply)
+  world:derive                   Derive obligations (--write, --out, --format human|json, --json)
 
 Gate semantics:
   phasegate:complete-check       Gate: lint + all validators; exits 1 on failure
@@ -780,6 +790,35 @@ Options:
   "phasegate:check-ready": `Usage: phasegate phasegate:check-ready
 
 Check whether the harness is ready (config valid, hooks deployed).`,
+  "world:inspect": `Usage: phasegate world:inspect [options]
+
+Inspect the read-only World snapshot without writing declarations or generated reports.
+
+Options:
+  --format <human|json>          Output format (default: human)
+  --json                         Alias for --format json
+  --help, -h                     Show this help`,
+  "world:pin": `Usage: phasegate world:pin --constraint <id> --endpoint <claimant|premise> [options]
+
+Preview a current endpoint digest. Use --apply to atomically update phasegate.world-constraints.json.
+
+Options:
+  --constraint <id>              pgw:v1:constraint ID
+  --endpoint <role>              claimant or premise
+  --apply                        Atomically apply the candidate
+  --format <human|json>          Output format (default: human)
+  --json                         Alias for --format json
+  --help, -h                     Show this help`,
+  "world:derive": `Usage: phasegate world:derive [options]
+
+Derive the immutable World obligation report. Default mode is pure and read-only.
+
+Options:
+  --write                        Persist the raw obligation report
+  --out <path>                   Override report path (requires --write)
+  --format <human|json>          Output format (default: human)
+  --json                         Alias for --format json
+  --help, -h                     Show this help`,
   "phasegate:complete-check": `Usage: phasegate phasegate:complete-check
 
 Run completion check (used by Stop hook). Validates phase-gate, metadata, and test-quality.`,
@@ -1838,6 +1877,21 @@ async function loadResolvedConfig(): Promise<HarnessConfigV2 | undefined> {
   }
 }
 
+async function loadWorldResolvedConfig() {
+  try {
+    const configModule = createConfigFoundationModule();
+    const result = await configModule.usecases.loadResolvedConfigUseCase.execute();
+    return {
+      designDocsRoot: result.config.paths.designDocs,
+      inceptionRoot: result.config.paths.inceptionDocs,
+      requirementMatrixPath: result.config.layers.L3.requirementMatrixPath,
+    };
+  } catch (error) {
+    if (error instanceof ConfigNotFoundError) return undefined;
+    throw error;
+  }
+}
+
 async function main(): Promise<void> {
   const args = process.argv.slice(2);
   const command = args[0];
@@ -1865,7 +1919,7 @@ async function main(): Promise<void> {
   const json = hasFlag(args, "--json");
 
   // Cross-unit wiring: 設定を先に解決し、各Unit に注入する
-  const resolvedConfig = await loadResolvedConfig();
+  const resolvedConfig = command.startsWith("world:") ? undefined : await loadResolvedConfig();
 
   try {
     switch (command) {
@@ -2664,6 +2718,58 @@ async function main(): Promise<void> {
         break;
       }
 
+      // ── world-model ──
+      case "world:inspect": {
+        let handler: WorldInspectCommandHandler;
+        try {
+          handler = createWorldModelModule({
+            rootDir,
+            resolvedConfig: await loadWorldResolvedConfig(),
+          }).worldInspectCommandHandler;
+        } catch (error) {
+          handler = WorldInspectCommandHandler.fromFailure(error);
+        }
+        const result = await handler.execute(args.slice(1));
+        if (result.stdout.length > 0) process.stdout.write(result.stdout);
+        if (result.stderr.length > 0) process.stderr.write(result.stderr);
+        process.exitCode = result.exitCode;
+        return;
+      }
+
+      case "world:pin": {
+        let handler: WorldPinCommandHandler;
+        try {
+          handler = createWorldModelModule({
+            rootDir,
+            resolvedConfig: await loadWorldResolvedConfig(),
+          }).worldPinCommandHandler;
+        } catch (error) {
+          handler = WorldPinCommandHandler.fromFailure(error);
+        }
+        const result = await handler.execute(args.slice(1));
+        if (result.stdout.length > 0) process.stdout.write(result.stdout);
+        if (result.stderr.length > 0) process.stderr.write(result.stderr);
+        process.exitCode = result.exitCode;
+        return;
+      }
+
+      case "world:derive": {
+        let handler: WorldDeriveCommandHandler;
+        try {
+          handler = createWorldModelModule({
+            rootDir,
+            resolvedConfig: await loadWorldResolvedConfig(),
+          }).worldDeriveCommandHandler;
+        } catch (error) {
+          handler = WorldDeriveCommandHandler.fromFailure(error);
+        }
+        const result = await handler.execute(args.slice(1));
+        if (result.stdout.length > 0) process.stdout.write(result.stdout);
+        if (result.stderr.length > 0) process.stderr.write(result.stderr);
+        process.exitCode = result.exitCode;
+        return;
+      }
+
       // ── phase-dependency-model ──
       case "check-phase-gate": {
         const phaseConfig = resolvedConfig ? toPhaseConfigSection(resolvedConfig) : undefined;