CradlePlugin으로 target 단위 Mermaid .mmd 개발 산출물을 생성하도록 구현한다

.agents/roles.md

@@ -21,7 +21,7 @@ Treat role assignment, approved Spec handoff, final review, and verification evi
 | Tier | Use | Model |
 | --- | --- | --- |
 | `Primary` | Planning, implementation, public API decisions, final integration, and failed-check triage | Active primary agent |
-| `SDD Gate` | Design analysis and final diff review | `gpt-5.6-sol`, `xhigh` |
+| `SDD Gate` | Design analysis and final diff review | `gpt-6-astra`, `xhigh` |
 | `Lightweight` | Read-only review, checklist verification, CI log summaries, documentation drafts, and architecture preflight | `gpt-5.3-codex-spark`; use `gpt-5.6-luna`, `high` only when unavailable |
 
 | Role | Owner or custom agent | Tier |
@@ -37,7 +37,7 @@ Treat role assignment, approved Spec handoff, final review, and verification evi
 
 ## Dispatch and Fallback Rules
 
-- `Designer` and `Code Reviewer` use only `gpt-5.6-sol`, `xhigh`, with no Luna fallback.
+- `Designer` and `Code Reviewer` use only `gpt-6-astra`, `xhigh`, with no Luna fallback.
 - Lightweight roles use Spark first and may use only the matching `*_luna` setting when Spark is unavailable.
 - A `*_luna` role must not replace `Designer`, `Code Reviewer`, `Planner`, or `Implementer`.
 - A side task `task_name` must exactly match the `.codex/agents/<name>.toml` filename without its extension.

.codex/agents/code_reviewer.toml

@@ -1,6 +1,6 @@
 name = "code_reviewer"
 description = "Read-only Cradle code reviewer for correctness, regressions, public API, Macro, concurrency, scope drift, and missing verification."
-model = "gpt-5.6-sol"
+model = "gpt-6-astra"
 model_reasoning_effort = "xhigh"
 sandbox_mode = "read-only"
 developer_instructions = """

.codex/agents/designer.toml

@@ -1,6 +1,6 @@
 name = "designer"
 description = "Read-only Cradle SDD gate for Design Brief analysis, public API boundaries, Spec acceptance criteria, verification, and minimum commit units."
-model = "gpt-5.6-sol"
+model = "gpt-6-astra"
 model_reasoning_effort = "xhigh"
 sandbox_mode = "read-only"
 developer_instructions = """

.gitignore

@@ -12,6 +12,9 @@ DerivedData/
 xcuserdata/
 *.xcuserstate
 
+# Mermaid 개발 산출물
+.cradle/
+
 # 인증·환경
 .netrc
 .env

Artifacts/CradleDiagramMaker.artifactbundle/info.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": "1.0",
+  "artifacts": {
+    "CradleDiagramMaker": {
+      "version": "0.1.0",
+      "type": "executable",
+      "variants": [
+        {
+          "path": "CradleDiagramMaker-arm64/bin/CradleDiagramMaker",
+          "supportedTriples": [
+            "arm64-apple-macosx"
+          ]
+        },
+        {
+          "path": "CradleDiagramMaker-x86_64/bin/CradleDiagramMaker",
+          "supportedTriples": [
+            "x86_64-apple-macosx"
+          ]
+        }
+      ]
+    }
+  }
+}

Examples/ExampleApp/ExampleApp.xcodeproj/project.pbxproj

@@ -165,10 +165,12 @@
 				A10000000000000000000006 /* Sources */,
 				A10000000000000000000007 /* Frameworks */,
 				A10000000000000000000008 /* Resources */,
+				A1000000000000000000003E /* Cradle Mermaid copy */,
 			);
 			buildRules = (
 			);
 			dependencies = (
+				A1000000000000000000003D /* PBXTargetDependency */,
 			);
 			name = ExampleApp;
 			packageProductDependencies = (
@@ -225,6 +227,28 @@
 		};
 /* End PBXResourcesBuildPhase section */
 
+/* Begin PBXShellScriptBuildPhase section */
+		A1000000000000000000003E /* Cradle Mermaid copy */ = {
+			isa = PBXShellScriptBuildPhase;
+			alwaysOutOfDate = 1;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			inputFileListPaths = (
+			);
+			inputPaths = (
+			);
+			name = "Cradle Mermaid copy";
+			outputFileListPaths = (
+			);
+			outputPaths = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+			shellPath = /bin/sh;
+			shellScript = "/bin/sh \"${SRCROOT}/Scripts/CopyCradleMermaid.sh\"";
+		};
+/* End PBXShellScriptBuildPhase section */
+
 /* Begin PBXSourcesBuildPhase section */
 		A10000000000000000000006 /* Sources */ = {
 			isa = PBXSourcesBuildPhase;
@@ -249,6 +273,13 @@
 		};
 /* End PBXSourcesBuildPhase section */
 
+/* Begin PBXTargetDependency section */
+		A1000000000000000000003D /* PBXTargetDependency */ = {
+			isa = PBXTargetDependency;
+			productRef = A1000000000000000000003C /* CradlePlugin */;
+		};
+/* End PBXTargetDependency section */
+
 /* Begin XCBuildConfiguration section */
 		A1000000000000000000000B /* Debug */ = {
 			isa = XCBuildConfiguration;
@@ -368,6 +399,10 @@
 			package = A1000000000000000000001B /* XCLocalSwiftPackageReference "Cradle" */;
 			productName = Cradle;
 		};
+		A1000000000000000000003C /* CradlePlugin */ = {
+			isa = XCSwiftPackageProductDependency;
+			productName = "plugin:CradlePlugin";
+		};
 /* End XCSwiftPackageProductDependency section */
 	};
 	rootObject = A10000000000000000000001 /* Project object */;

Examples/ExampleApp/Scripts/CopyCradleMermaid.sh

@@ -0,0 +1,89 @@
+#!/bin/sh
+
+set -eu
+
+search_root="${OBJROOT}/BuildToolPluginIntermediates"
+destination_directory="${SRCROOT}/.cradle"
+destination="${destination_directory}/DependencyGraph.mmd"
+matches="${TARGET_TEMP_DIR}/cradle-diagram-paths.txt"
+temporary=""
+
+cleanup() {
+	/bin/rm -f "${matches}"
+
+	if [ -n "${temporary}" ]; then
+		/bin/rm -f "${temporary}"
+	fi
+}
+
+trap cleanup EXIT
+
+: > "${matches}"
+
+case "${TARGET_NAME}" in
+	*/*)
+		echo "warning: Xcode target 이름에 경로 구분자가 있어 기존 파일을 유지합니다."
+		exit 0
+		;;
+esac
+
+target_path_pattern=$(printf '%s' "${TARGET_NAME}" | /usr/bin/sed 's/[][\\*?]/\\&/g')
+
+if [ -d "${search_root}" ]; then
+	if ! /usr/bin/find "${search_root}" \
+		-type f \
+		! -type l \
+		-path "*/${target_path_pattern}/CradlePlugin/CradleDiagrams/*/DependencyGraph.mmd" \
+		-print > "${matches}"; then
+		echo "warning: Cradle DependencyGraph.mmd를 찾지 못해 기존 파일을 유지합니다."
+		exit 0
+	fi
+fi
+
+count=$(/usr/bin/wc -l < "${matches}" | /usr/bin/tr -d ' ')
+
+if [ "${count}" -ne 1 ]; then
+	echo "warning: Cradle DependencyGraph.mmd 후보를 하나로 결정하지 못해 기존 파일을 유지합니다."
+	exit 0
+fi
+
+source_path=$(/usr/bin/sed -n '1p' "${matches}")
+
+if [ ! -f "${source_path}" ] || [ -L "${source_path}" ]; then
+	echo "warning: Cradle DependencyGraph.mmd가 없어 기존 파일을 유지합니다."
+	exit 0
+fi
+
+if [ -L "${destination_directory}" ] || { [ -e "${destination_directory}" ] && [ ! -d "${destination_directory}" ]; }; then
+	echo "warning: .cradle 경로를 안전하게 쓸 수 없어 기존 파일을 유지합니다."
+	exit 0
+fi
+
+if [ -L "${destination}" ] || { [ -e "${destination}" ] && [ ! -f "${destination}" ]; }; then
+	echo "warning: DependencyGraph.mmd 경로를 안전하게 쓸 수 없어 기존 파일을 유지합니다."
+	exit 0
+fi
+
+if ! /bin/mkdir -p "${destination_directory}"; then
+	echo "warning: .cradle 디렉터리를 만들지 못해 기존 파일을 유지합니다."
+	exit 0
+fi
+
+if [ -f "${destination}" ] && /usr/bin/cmp -s "${source_path}" "${destination}"; then
+	exit 0
+fi
+
+if ! temporary=$(/usr/bin/mktemp "${destination_directory}/.DependencyGraph.mmd.XXXXXX"); then
+	echo "warning: Cradle DependencyGraph.mmd 임시 파일을 만들지 못해 기존 파일을 유지합니다."
+	exit 0
+fi
+
+if ! /bin/cp "${source_path}" "${temporary}"; then
+	echo "warning: Cradle DependencyGraph.mmd 복사에 실패해 기존 파일을 유지합니다."
+	exit 0
+fi
+
+if ! /bin/mv -f "${temporary}" "${destination}"; then
+	echo "warning: Cradle DependencyGraph.mmd 반영에 실패해 기존 파일을 유지합니다."
+	exit 0
+fi

Package.swift

@@ -14,6 +14,10 @@ let package = Package(
 		.library(
 			name: "CradleTesting",
 			targets: ["CradleTesting"]
+		),
+		.plugin(
+			name: "CradlePlugin",
+			targets: ["CradlePlugin"]
 		)
 	],
 	dependencies: [
@@ -23,6 +27,34 @@ let package = Package(
 		)
 	],
 	targets: [
+		.target(
+			name: "CradleGraphAnalysis",
+			dependencies: [
+				.product(name: "SwiftSyntax", package: "swift-syntax"),
+				.product(name: "SwiftSyntaxBuilder", package: "swift-syntax")
+			]
+		),
+		.target(
+			name: "CradleDiagramMakerSupport",
+			dependencies: [
+				"CradleGraphAnalysis",
+				.product(name: "SwiftParser", package: "swift-syntax")
+			]
+		),
+		.executableTarget(
+			name: "CradleDiagramMakerSource",
+			dependencies: ["CradleDiagramMakerSupport"],
+			path: "Sources/CradleDiagramMaker"
+		),
+		.binaryTarget(
+			name: "CradleDiagramMaker",
+			path: "Artifacts/CradleDiagramMaker.artifactbundle"
+		),
+		.plugin(
+			name: "CradlePlugin",
+			capability: .buildTool(),
+			dependencies: ["CradleDiagramMaker"]
+		),
 		.macro(
 			name: "CradleMacros",
 			dependencies: [
@@ -40,6 +72,19 @@ let package = Package(
 			dependencies: ["Cradle"],
 			path: "Tests/CradleConsumerFixture"
 		),
+		.testTarget(
+			name: "CradleGraphAnalysisTests",
+			dependencies: [
+				"CradleGraphAnalysis",
+				.product(name: "SwiftParser", package: "swift-syntax"),
+				.product(name: "SwiftSyntax", package: "swift-syntax"),
+				.product(name: "SwiftSyntaxBuilder", package: "swift-syntax")
+			]
+		),
+		.testTarget(
+			name: "CradleDiagramMakerSupportTests",
+			dependencies: ["CradleDiagramMakerSupport"]
+		),
 		.testTarget(
 			name: "CradleTests",
 			dependencies: ["Cradle", "CradleConsumerFixture", "CradleTesting"]

Plugins/CradlePlugin/CradlePlugin.swift

@@ -0,0 +1,84 @@
+//
+//  CradlePlugin.swift
+//  CradlePlugin
+//
+//  Created by opfic on 9/4/26.
+//
+
+import Foundation
+import PackagePlugin
+
+#if canImport(XcodeProjectPlugin)
+import XcodeProjectPlugin
+#endif
+
+// target source의 DependencyGraph Mermaid `.mmd` 산출물을 만드는 Build Tool Plugin
+@main
+struct CradlePlugin: BuildToolPlugin {
+	// 현재 SwiftPM source target을 단위로 Mermaid 생성 명령 구성
+	func createBuildCommands(context: PluginContext, target: Target) async throws -> [Command] {
+		guard let sourceTarget = target as? SwiftSourceModuleTarget else {
+			return []
+		}
+		let tool = try context.tool(named: "CradleDiagramMaker")
+		let sourcePaths = sourceTarget.sourceFiles
+			.filter { $0.type == .source }
+			.map(\.url)
+			.sorted { $0.path < $1.path }
+		return mermaidBuildCommands(
+			toolURL: tool.url,
+			pluginWorkDirectoryURL: context.pluginWorkDirectoryURL,
+			moduleName: sourceTarget.moduleName,
+			sourceURLs: sourcePaths
+		)
+	}
+}
+
+#if canImport(XcodeProjectPlugin)
+// Xcode 프로젝트 target의 Mermaid 생성 진입점
+extension CradlePlugin: XcodeBuildToolPlugin {
+	// 현재 Xcode target source를 단위로 Mermaid 생성 명령 구성
+	func createBuildCommands(context: XcodePluginContext, target: XcodeTarget) throws -> [Command] {
+		let tool = try context.tool(named: "CradleDiagramMaker")
+		let sourceURLs = target.inputFiles
+			.map(\.url)
+			.filter { $0.pathExtension == "swift" }
+			.sorted { $0.path < $1.path }
+		// 표시 이름을 Swift module로 해석하지 않고 단일 출력 경로 요소로 변환
+		let allowed = CharacterSet.alphanumerics.union(CharacterSet(charactersIn: "_- "))
+		let namespace = target.displayName.addingPercentEncoding(withAllowedCharacters: allowed) ?? target.id
+		return mermaidBuildCommands(
+			toolURL: tool.url,
+			pluginWorkDirectoryURL: context.pluginWorkDirectoryURL,
+			moduleName: namespace,
+			sourceURLs: sourceURLs
+		)
+	}
+}
+#endif
+
+// SwiftPM·Xcode target의 입력 변경과 반복 빌드에 적용할 Mermaid 명령 구성
+private func mermaidBuildCommands(
+	toolURL: URL,
+	pluginWorkDirectoryURL: URL,
+	moduleName: String,
+	sourceURLs: [URL]
+) -> [Command] {
+	let outputDirectory = pluginWorkDirectoryURL.appendingPathComponent("CradleDiagrams")
+	let arguments = [
+		"--module", moduleName,
+		"--output", outputDirectory.path
+	]
+		+ sourceURLs.map(\.path)
+
+	return [
+		// `.mmd`를 resource로 등록하지 않고 매 빌드에서 기존 파일 정리까지 수행
+		.buildCommand(
+			displayName: "Cradle Mermaid diagrams",
+			executable: toolURL,
+			arguments: arguments,
+			inputFiles: sourceURLs,
+			outputFiles: []
+		)
+	]
+}

README.md

@@ -0,0 +1,19 @@
+# Cradle
+
+Cradle은 Swift Macro를 사용해 의존성 graph의 factory를 생성하는 라이브러리입니다.
+
+## Mermaid 개발 산출물
+
+`CradlePlugin`은 build 중 Mermaid 원본을 생성합니다. Xcode에서 바로 열 파일이 필요하면 target의 마지막 Run Script 단계가 `.cradle/DependencyGraph.mmd`로 복사하게 설정할 수 있습니다.
+
+### ExampleApp 설정
+
+`Examples/ExampleApp`의 `Cradle Mermaid copy` 단계는 [CopyCradleMermaid.sh](Examples/ExampleApp/Scripts/CopyCradleMermaid.sh)를 실행합니다. 같은 설정을 추가할 때는 이 단계를 target의 마지막 Build Phase에 두고 Based on dependency analysis를 선택 해제합니다.
+
+```sh
+/bin/sh "${SRCROOT}/Scripts/CopyCradleMermaid.sh"
+```
+
+`Cmd+B`를 마치면 `Examples/ExampleApp/.cradle/DependencyGraph.mmd`가 생성됩니다. `.cradle/`은 Git에서 제외되며 앱이나 라이브러리 제품에 포함되지 않습니다.
+
+Xcode의 build 도구 작업 경로는 공개된 고정 경로가 아닙니다. 이 설정은 현재 `CradlePlugin` 산출물을 쉽게 열기 위한 방법이므로, Xcode 구조가 바뀐 뒤 경고가 나오면 [CopyCradleMermaid.sh](Examples/ExampleApp/Scripts/CopyCradleMermaid.sh)의 검색 경로를 확인해야 합니다.