@ccdd/core 2.0.1 → 2.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +75 -259
- package/examples/artifact-groups/README.md +21 -28
- package/examples/artifact-groups/ccdd.config.ts +6 -6
- package/examples/artifact-groups/effect.md +8 -8
- package/examples/custom-text-reader/README.md +9 -9
- package/examples/custom-text-reader/ccdd.config.ts +3 -3
- package/examples/custom-text-reader/spec.md +2 -2
- package/examples/custom-text-reader/why.md +1 -1
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,301 +1,117 @@
|
|
|
1
1
|
# CCDD
|
|
2
2
|
|
|
3
|
-
**
|
|
3
|
+
**Check that the pieces of your project fit together.**
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
| --- | --- |
|
|
7
|
-
| `@ccdd/core` | `defineConfig`, `defineTool`, Artifact·Critic·stale 전략 타입. 실행 의존성과 DB가 없습니다. |
|
|
8
|
-
| `@ccdd/project` | 현재 검증 조회, 필요한 검증 의뢰, 실제 판정 이력, Broker·실행기·모니터. |
|
|
9
|
-
| `@ccdd/default-tools` | 프로젝트가 선택하여 명시적으로 등록하는 관측 도구. |
|
|
10
|
-
|
|
11
|
-
## 시작하기
|
|
12
|
-
|
|
13
|
-
Node.js 24 이상이 필요합니다. 공개 npm 배포를 지원하며, 첫 게시가 완료된 버전부터 리뷰 대상 프로젝트에 다음과 같이 설치할 수 있습니다. npm 게시 절차와 버전 확인은 [배포 안내](docs/releases.md#npm-공개-배포)를 참고하세요.
|
|
14
|
-
|
|
15
|
-
```sh
|
|
16
|
-
npm init -y
|
|
17
|
-
npm pkg set type=module
|
|
18
|
-
npm install --ignore-scripts @ccdd/core @ccdd/project @ccdd/default-tools
|
|
19
|
-
npx ccdd-project help
|
|
20
|
-
```
|
|
21
|
-
|
|
22
|
-
GitHub에 같은 버전의 Release가 게시된 경우 tarball로도 설치할 수 있습니다. 다음은 v2.0.1 게시 후의 설치 명령입니다. 다운로드에는 저장소 접근 권한이 있는 GitHub CLI 로그인이 필요합니다.
|
|
23
|
-
|
|
24
|
-
```sh
|
|
25
|
-
npm init -y
|
|
26
|
-
npm pkg set type=module
|
|
27
|
-
mkdir -p vendor/ccdd
|
|
28
|
-
gh release download v2.0.1 --repo lhj6102/ccdd --dir vendor/ccdd \
|
|
29
|
-
--pattern '*.tgz' --pattern SHA256SUMS --pattern verification.json
|
|
30
|
-
(cd vendor/ccdd && shasum -a 256 -c SHA256SUMS)
|
|
31
|
-
npm install --ignore-scripts \
|
|
32
|
-
./vendor/ccdd/ccdd-core-2.0.1.tgz \
|
|
33
|
-
./vendor/ccdd/ccdd-project-2.0.1.tgz \
|
|
34
|
-
./vendor/ccdd/ccdd-default-tools-2.0.1.tgz
|
|
35
|
-
npx ccdd-project help
|
|
36
|
-
```
|
|
5
|
+
A project has requirements, designs, tests, and implementations. CCDD connects these pieces to the checks that review them. An AI agent can compare a design with its requirements, a person can inspect an image, and a test runner can check an implementation.
|
|
37
6
|
|
|
38
|
-
|
|
7
|
+
You choose the materials, the review criteria, and the tools reviewers can use. CCDD keeps track of what was reviewed and which checks are still needed.
|
|
39
8
|
|
|
40
|
-
|
|
41
|
-
nvm use # nvm 사용 시 .nvmrc의 Node 24 선택
|
|
42
|
-
npm ci
|
|
43
|
-
npm run build
|
|
44
|
-
node dist/src/project/cli.js help
|
|
45
|
-
node dist/src/project/cli.js config check --repo /path/to/project
|
|
46
|
-
node dist/src/project/cli.js plan spec --recursive --repo /path/to/project
|
|
47
|
-
node dist/src/project/cli.js verify spec --recursive --wait --repo /path/to/project
|
|
48
|
-
node dist/src/project/cli.js status spec --repo /path/to/project
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
리뷰할 프로젝트에는 아래 예제처럼 `ccdd.config.ts`와 그 설정이 가리키는 파일을 둡니다. 설정이 import하는 core와 선택한 도구 라이브러리는 그 프로젝트에도 설치해야 합니다. 세 패키지를 설치하면 `npx ccdd-project`를 사용할 수 있습니다. 기본 도구 없이 custom 도구를 사용한다면 core와 Project를 설치합니다. 정의만 사용하는 프로젝트는 core만 설치할 수 있습니다.
|
|
52
|
-
|
|
53
|
-
`status`·`plan`은 현재 입력에 적용 가능한 실제 판정을 조회합니다. `verify`는 필요한 검증을 의뢰하며 기본 입력 정책은 copy입니다. `--recursive`가 없으면 선택한 Critic 중 실행 가능한 것부터 진행하고, 선행 검증이 필요한 항목은 미완료로 보고합니다. 검증 조회는 Provider나 리뷰 도구를 실행하지 않습니다. TS 설정의 평가는 명시적인 현재 입력 조회 시 일어납니다.
|
|
54
|
-
|
|
55
|
-
```ts
|
|
56
|
-
artifacts: {
|
|
57
|
-
why: { type: 'markdown', path: 'why.md', basis: true },
|
|
58
|
-
spec: { type: 'markdown', path: 'spec.md',
|
|
59
|
-
stale: { kind: 'file-hash', paths: ['spec.md', 'references'] } },
|
|
60
|
-
}
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
기본 동일성 기준은 Artifact 경로의 파일 내용 hash입니다. `paths`로 별도 입력 경로들을 선언하거나 `{ kind: 'always' }`로 요청마다 검증하게 할 수 있습니다. 설정한 경로들은 Artifact의 의미에 영향을 주는 입력을 빠짐없이 포함해야 합니다.
|
|
64
|
-
|
|
65
|
-
Why → Spec → Tests → Implementation에서 Why가 바뀌면 Spec의 검증 입력이 바뀝니다. Spec이 내용 수정 없이 다시 PASS하면 Tests의 target·직접 deps hash는 그대로이므로 이전 실제 PASS를 재사용합니다. 하위 노드에 stale 상태를 전파하거나 저장하지 않고 조회마다 DAG를 재귀적으로 평가합니다.
|
|
9
|
+
## How it fits together
|
|
66
10
|
|
|
67
|
-
|
|
11
|
+
**Blue dashed lines: configuration. Orange solid lines: requests and reviews.**
|
|
68
12
|
|
|
69
|
-
|
|
13
|
+
```mermaid
|
|
14
|
+
flowchart LR
|
|
15
|
+
subgraph PROJECT["Your project"]
|
|
16
|
+
direction TB
|
|
17
|
+
REQUIREMENTS["Requirements"]
|
|
18
|
+
DESIGN["Design"]
|
|
19
|
+
TESTS["Tests"]
|
|
20
|
+
IMPLEMENTATION["Implementation"]
|
|
70
21
|
|
|
71
|
-
|
|
22
|
+
REQUIREMENTS -.->|"Design Critic"| DESIGN
|
|
23
|
+
REQUIREMENTS -.->|"Test Critic"| TESTS
|
|
24
|
+
DESIGN -.->|"Implementation Critic"| IMPLEMENTATION
|
|
25
|
+
TESTS -.->|"Implementation Critic"| IMPLEMENTATION
|
|
26
|
+
end
|
|
72
27
|
|
|
73
|
-
|
|
28
|
+
subgraph CCDD["CCDD"]
|
|
29
|
+
direction TB
|
|
30
|
+
ARTIFACTS["Artifact layer<br/>Materials and tools"]
|
|
31
|
+
VALIDATION["Validation<br/>Checks, reuse, and reviews"]
|
|
32
|
+
end
|
|
74
33
|
|
|
75
|
-
|
|
34
|
+
subgraph REVIEWERS["Reviewers"]
|
|
35
|
+
REVIEWER["AI agent<br/>Person<br/>Test runner"]
|
|
36
|
+
end
|
|
76
37
|
|
|
77
|
-
|
|
38
|
+
PROJECT -.->|"Register Artifacts and tools"| ARTIFACTS
|
|
39
|
+
PROJECT -.->|"Define Critics"| VALIDATION
|
|
40
|
+
PROJECT <-->|"Request / result"| VALIDATION
|
|
41
|
+
VALIDATION <-->|"Review / findings"| REVIEWER
|
|
42
|
+
ARTIFACTS <-->|"Access / observations"| REVIEWER
|
|
78
43
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
```ts
|
|
82
|
-
artifacts: {
|
|
83
|
-
effect: { type: 'markdown', path: 'effect.md' },
|
|
84
|
-
preview: { type: 'image', path: 'preview.png' },
|
|
85
|
-
explosion: { kind: 'group', members: ['effect', 'preview'] },
|
|
86
|
-
}
|
|
44
|
+
linkStyle 0,1,2,3,4,5 stroke:#3b82f6,stroke-width:2px
|
|
45
|
+
linkStyle 6,7,8 stroke:#f59e0b,stroke-width:3px
|
|
87
46
|
```
|
|
88
47
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
## Agent Provider와 인증
|
|
48
|
+
Three terms explain the picture:
|
|
92
49
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
```json
|
|
96
|
-
{"kind":"agent","provider":"openai-codex","model":"gpt-6-astra","reasoning":"medium"}
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
`@earendil-works/pi-agent-core`와 `@earendil-works/pi-ai` 0.85.1을 라이브러리로 사용합니다. Provider 호출과 Agent 도구 루프는 Agent 실행기 내부의 Pi가 맡으며, CCDD가 판정 스키마·필수 Artifact 관측·workspace 무결성을 검증합니다. 기본 이미지 도구도 내부 CLI에서 Pi의 read를 재사용하지만 세션이나 Provider 호출은 만들지 않습니다. Broker·Human·Runtime은 Pi 세션을 사용하지 않습니다.
|
|
100
|
-
|
|
101
|
-
Provider API key 환경변수는 Pi의 Provider별 규칙을 따릅니다. 파일 인증은 명시적으로 연결합니다.
|
|
102
|
-
|
|
103
|
-
```sh
|
|
104
|
-
ccdd doctor --repo /path/to/project --pi-auth-file /outside/repo/pi-auth.json --json
|
|
105
|
-
ccdd run --repo /path/to/project --copy --pi-auth-file /outside/repo/pi-auth.json --wait
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
Pi 파일 형식은 Provider ID별 credential 객체입니다. 예를 들어 API key는 `{"anthropic":{"type":"api_key","key":"..."}}`, OAuth는 `{"openai-codex":{"type":"oauth","access":"...","refresh":"...","expires":1234567890000}}` 형태입니다. 토큰은 해당 로그인 도구에서 발급받으며, repo와 리뷰 상태에 저장하지 않습니다.
|
|
109
|
-
|
|
110
|
-
기존 Codex 인증을 사용할 때도 경로를 직접 지정합니다.
|
|
111
|
-
|
|
112
|
-
```sh
|
|
113
|
-
ccdd doctor --repo /path/to/project --codex-auth-file "$HOME/.codex/auth.json" --json
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
이 연결은 유효한 access token만 읽으며 공유 refresh token을 Pi에 전달하거나 파일을 변경하지 않습니다. Pi 인증 파일도 현재는 읽기 전용으로 연결합니다. 만료됐거나 5분 안에 만료될 OAuth는 거부하며, 발급 도구에서 인증을 갱신한 뒤 다시 실행해야 합니다. 인증을 자동 승계하거나 로그인·갱신을 대신하지 않습니다.
|
|
117
|
-
|
|
118
|
-
환경변수 `CCDD_PI_AUTH_FILE`·`CCDD_CODEX_AUTH_FILE`로 경로를 지정할 수도 있습니다. worker에는 경로만 저장하고, Human 결과 제출이나 `resume`은 원래 실행 설정을 다시 사용합니다. Provider API key 환경변수는 실행·재개 프로세스에서 사용할 수 있어야 합니다.
|
|
119
|
-
|
|
120
|
-
미지원 Provider·모델·reasoning을 다른 설정으로 대체하지 않습니다. 기존 `provider: "codex"`는 Pi의 `openai-codex`로 명시적으로 바꿔야 합니다. Pi 0.85.1은 `openai`와 `openai-codex`의 `gpt-6-astra`를 지원합니다. Astra reasoning은 `low`·`medium`·`high`·`xhigh`·`max`를 그대로 적용하며, `off`·`minimal`·`ultra`는 거부합니다. 새 데모는 `openai-codex / gpt-6-astra / medium`을 명시합니다. 현재 지원 범위는 [Pi 공식 문서](https://github.com/earendil-works/pi/tree/main/packages/ai)를 참고하고, 실제 접근은 `doctor`로 확인하세요.
|
|
121
|
-
|
|
122
|
-
## 리뷰 입력 선택
|
|
123
|
-
|
|
124
|
-
`run`은 `--copy` 또는 `--lock` 중 하나를 명시해야 합니다. 두 옵션을 동시에 사용할 수 없습니다.
|
|
125
|
-
|
|
126
|
-
| 옵션 | 입력 | 수정 정책 |
|
|
50
|
+
| Term | Meaning | Example |
|
|
127
51
|
| --- | --- | --- |
|
|
128
|
-
|
|
|
129
|
-
|
|
|
130
|
-
|
|
131
|
-
커밋 여부와 ignore 규칙에 관계없이 모든 파일이 대상입니다. `.git`, 의존성 디렉터리, 새 파일도 포함합니다. 상대경로·내용·파일 유형·실행 권한으로 계산한 SHA-256이 같은 복사본은 동시에 여러 리뷰에서 재사용합니다. 판정은 매번 실행하며, 입력 공유가 판정 재사용을 의미하지 않습니다.
|
|
132
|
-
|
|
133
|
-
공유 복사본은 읽기 전용입니다. 테스트 출력은 `CCDD_OUTPUT_DIR`, 임시 파일은 `CCDD_TMP_DIR` 또는 `TMPDIR`에 작성합니다. CCDD의 상태·로그·복사본·리뷰 출력은 repo 밖에 저장합니다. 기본 경로는 `~/.local/state/ccdd/<repo 식별자>`이며, `--state-dir` 또는 `CCDD_STATE_HOME`으로 변경합니다.
|
|
134
|
-
|
|
135
|
-
`--lock`은 쓰기를 강제로 막는 기능이 아닙니다. 파일 이벤트와 메타데이터, 내용 검증으로 변경을 감시합니다. 감시할 수 없는 환경에서는 실행을 거부합니다. 원본을 수정한 후 내용을 되돌려도 변경으로 검출되면 실패합니다. 자세한 범위와 제한은 [workspace 계약](docs/contracts.md)을 참고하세요.
|
|
136
|
-
|
|
137
|
-
## Artifact 도구 설정
|
|
138
|
-
|
|
139
|
-
설정은 `ccdd.config.ts`입니다. 프로젝트 `package.json`의 `type`은 `module`로 지정합니다(`npm pkg set type=module`). 설정 객체 또는 객체를 반환하는 동기·비동기 함수를 default export합니다. `@ccdd/core`는 가벼운 `defineConfig`, `defineTool`과 도구 타입을 제공하고, `@ccdd/default-tools`는 선택적으로 설치하는 구현 라이브러리입니다. import하거나 factory를 호출하는 것만으로 파일을 읽거나 프로그램을 실행하지 않습니다.
|
|
140
|
-
|
|
141
|
-
```ts
|
|
142
|
-
import { defineConfig } from '@ccdd/core';
|
|
143
|
-
import { agent, human } from '@ccdd/default-tools';
|
|
144
|
-
|
|
145
|
-
export default defineConfig(() => ({
|
|
146
|
-
artifactTypes: {
|
|
147
|
-
markdown: {
|
|
148
|
-
agentTools: { read: agent.text.read() },
|
|
149
|
-
humanTools: { open: human.desktop.open() },
|
|
150
|
-
},
|
|
151
|
-
code: {
|
|
152
|
-
agentTools: { list: agent.files.list(), read: agent.files.read() },
|
|
153
|
-
humanTools: { open: human.desktop.open() },
|
|
154
|
-
},
|
|
155
|
-
},
|
|
156
|
-
artifacts: {
|
|
157
|
-
why: { type: 'markdown', path: 'why.md', basis: true },
|
|
158
|
-
spec: { type: 'markdown', path: 'spec.md' },
|
|
159
|
-
},
|
|
160
|
-
critics: [{
|
|
161
|
-
id: 'spec-why', title: 'Spec이 Why에 부합하는가', target: 'spec', deps: ['why'],
|
|
162
|
-
profile: { kind: 'agent', provider: 'openai-codex', model: 'gpt-6-astra', reasoning: 'medium' },
|
|
163
|
-
payload: { instruction: '{spec}이 {why}의 요구사항을 충족하는지 검토하세요.' },
|
|
164
|
-
}],
|
|
165
|
-
}));
|
|
166
|
-
```
|
|
52
|
+
| **Artifact** | A named file, folder, or group of materials to review. | `spec.md`, `tests/`, or an image. |
|
|
53
|
+
| **Critic** | A check with one target, reference materials, and a reviewer. | “Does this design meet these requirements?” |
|
|
54
|
+
| **Artifact tool** | A way for a reviewer to inspect an Artifact. | Read text, view an image, or open a desktop application. |
|
|
167
55
|
|
|
168
|
-
|
|
56
|
+
Each Critic declares its target and references. These relationships form a directed acyclic graph, or **DAG**: checks can branch and join, but cannot depend on themselves through a cycle. The two Implementation arrows above belong to one Critic that references both Design and Tests. Requirements are an explicitly accepted starting point in this example.
|
|
169
57
|
|
|
170
|
-
|
|
58
|
+
## What you do
|
|
171
59
|
|
|
172
|
-
|
|
60
|
+
1. **Name your materials.** Give each Artifact an ID, a type, and a file or folder path. Groups collect existing Artifacts.
|
|
61
|
+
2. **Connect tools.** Use the optional default tools or write your own `metadata` and `execute` function. Register them by Artifact type in `ccdd.config.ts`.
|
|
62
|
+
3. **Define checks.** For each Critic, choose the target, its references, the review criteria, and an Agent, Human, or Runtime reviewer.
|
|
63
|
+
4. **Request a review.** Read the findings, update your project, and request another check when needed.
|
|
173
64
|
|
|
174
|
-
|
|
65
|
+
For example, a document tool registered as `read` becomes `read_spec` when connected to the `spec` Artifact. CCDD gives the Agent its name, description, and input schema. When the Agent calls it, CCDD invokes your local `execute` function against the fixed review input and returns the content to the Agent.
|
|
175
66
|
|
|
176
|
-
|
|
67
|
+
Artifact types act as plugin slots through explicit registration. Importing a tool library does not register or run its tools. Agent and Human tools are registered separately; Runtime reviewers execute configured Node tests against the declared inputs.
|
|
177
68
|
|
|
178
|
-
|
|
69
|
+
## Try your first review
|
|
179
70
|
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
### 지시사항의 Artifact 참조
|
|
183
|
-
|
|
184
|
-
`payload.instruction`에서 `{spec}`처럼 요청 범위의 Artifact ID를 참조할 수 있습니다. 위 예제는 Agent 프롬프트에서 다음과 같이 펼쳐집니다.
|
|
185
|
-
|
|
186
|
-
```text
|
|
187
|
-
{"artifact":"spec","tools":["read_spec"]}이 {"artifact":"why","tools":["read_why"]}의 요구사항을 충족하는지 검토하세요.
|
|
188
|
-
```
|
|
189
|
-
|
|
190
|
-
`tools`에는 해당 Artifact에 실제로 제공된 Agent 도구 이름이 들어갑니다. custom 도구를 등록했다면 그 이름을 사용합니다. Human 요청에서는 참조를 버튼으로 표시하고 연결된 Human 도구의 선택 영역으로 이동합니다. 참조 버튼만 눌러서는 도구가 실행되지 않으며, claim 후 실행할 도구를 명시적으로 선택합니다.
|
|
191
|
-
|
|
192
|
-
그룹 참조 `{explosion}`은 `{"artifactGroup":"explosion","members":[{"artifact":"effect","tools":["read_effect"]},{"artifact":"preview","tools":["view_image_preview"]}]}`처럼 구성원의 실제 도구 목록으로 펼칩니다. Human 화면에서는 해당 멤버의 도구를 고르는 버튼으로 표시합니다.
|
|
193
|
-
|
|
194
|
-
설정·저장된 요청·HTTP 응답의 `instruction` 문자열은 원문을 유지합니다. 다른 payload 필드도 바꾸지 않습니다. JSON 객체처럼 중괄호로 묶인 구간, 중첩·이중 중괄호, `\{spec}`처럼 escape한 참조, 알 수 없거나 요청 범위 밖인 ID, `{spec.path}` 같은 표현식은 그대로 둡니다. instruction을 일반 JSON 문서로 해석하지 않으므로 그 구간 밖의 따옴표나 배열 안에서도 `{spec}`은 참조입니다. 문자 그대로 쓰려면 escape합니다. 참조는 파일 본문을 삽입하거나 접근 범위를 늘리지 않습니다. 도구 설명의 `{artifactName}`은 그 도구에 연결된 ID를 치환하는 별도 규칙이며, instruction에 같은 이름의 예약변수를 추가하지 않습니다.
|
|
195
|
-
|
|
196
|
-
## 실행과 기록
|
|
71
|
+
You need **Node.js 24 or later**. For published packages, install:
|
|
197
72
|
|
|
198
73
|
```sh
|
|
199
|
-
|
|
200
|
-
ccdd status RUN_ID --wait --json
|
|
201
|
-
ccdd list
|
|
202
|
-
ccdd request REQUEST_ID
|
|
203
|
-
ccdd cancel RUN_ID
|
|
204
|
-
ccdd status RUN_ID --state-dir /outside/repo/state
|
|
74
|
+
npm install --ignore-scripts @ccdd/core @ccdd/project
|
|
205
75
|
```
|
|
206
76
|
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
원본 폴더가 삭제된 복사본 리뷰도 `--state-dir`만 지정하면 기록 조회와 Human 응답을 이어갈 수 있습니다.
|
|
210
|
-
|
|
211
|
-
각 Run은 독립된 실행 프로세스를 가집니다. 요청 CLI가 종료되거나 대기 시간이 초과돼도 실행 프로세스는 계속 작업합니다. `--wait`의 종료 코드는 `0=GREEN`, `1=RED`, `2=ERROR`, `3=대기 시간 초과`입니다. `--wait`를 생략한 종료 코드 0은 접수 성공입니다.
|
|
77
|
+
Follow [Your first review](docs/getting-started.md) for a complete, small example that runs a real test without an AI account. It also covers installation from local packages when a version has not been published.
|
|
212
78
|
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
[Builder 사용법](docs/builder-workflow.md) · [요청 계약](docs/requester-contract.md)
|
|
216
|
-
|
|
217
|
-
## Human 리뷰
|
|
218
|
-
|
|
219
|
-
`--human-inbox`는 repo 밖의 `human-inbox.jsonl`을 명시적인 알림 수단으로 등록합니다. Human 실행에는 최소 하나의 알림 수단이 필요하며, 알림 전달 실패는 `ERROR`입니다.
|
|
79
|
+
Once your project has a configuration, the usual loop is:
|
|
220
80
|
|
|
221
81
|
```sh
|
|
222
|
-
ccdd
|
|
223
|
-
ccdd
|
|
224
|
-
ccdd
|
|
225
|
-
ccdd
|
|
82
|
+
npx ccdd-project status
|
|
83
|
+
npx ccdd-project plan implementation --recursive
|
|
84
|
+
npx ccdd-project verify implementation --recursive --wait
|
|
85
|
+
npx ccdd-project history implementation
|
|
226
86
|
```
|
|
227
87
|
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
모니터에서도 Human 카드를 열어 **리뷰 맡기 → 도구 실행 → 성공·실패 판정 제출**을 진행할 수 있습니다. Claim한 브라우저만 해당 도구와 제출 버튼을 사용할 수 있습니다. 판정에는 요약과 최소 하나의 근거가 필요합니다. 서버를 재시작해도 같은 브라우저에서 이어갈 수 있으며, 브라우저 쿠키를 삭제하면 해당 브라우저의 담당 식별자가 사라집니다.
|
|
231
|
-
|
|
232
|
-
## Artifact 도구 검사
|
|
88
|
+
`status` and `plan` explain what is needed without starting reviews. `verify --recursive` includes any required earlier checks. To review only the selected scope, omit `--recursive`; blocked checks are reported as incomplete.
|
|
233
89
|
|
|
234
|
-
|
|
235
|
-
ccdd tools check --repo /path/to/project
|
|
236
|
-
ccdd tools check --artifact spec --for human
|
|
237
|
-
ccdd tools check --artifact spec --for human --tool open --execute
|
|
238
|
-
ccdd tools check --artifact tests --for agent --tool read --execute --args '{"path":"rank.test.mjs","startLine":1,"lineCount":30}'
|
|
239
|
-
```
|
|
240
|
-
|
|
241
|
-
기본 검사는 도구 정의·Artifact 경로와 등록된 `preflight`를 확인합니다. custom preflight가 없으면 등록 확인과 실제 실행 미검증을 구분하여 표시합니다. `--execute`는 지정한 도구를 실제로 호출하며, Human `open` 도구라면 프로그램이 열립니다. 실제 실행에는 Artifact·리뷰어 종류·도구를 모두 지정합니다. `--copy`가 기본이며, `--lock`도 지원합니다.
|
|
90
|
+
## What you get back
|
|
242
91
|
|
|
243
|
-
|
|
92
|
+
A completed review contains a **verdict, a summary, and concrete evidence**. GREEN means that Critic's criteria were met; RED means they were not. An execution problem is reported as ERROR. All required Critics must pass before their Artifact satisfies a dependent check.
|
|
244
93
|
|
|
245
|
-
|
|
94
|
+
CCDD can reuse an actual passing review when its criteria, target, and direct reference materials still match and its dependencies are satisfied. An unchanged intermediate Artifact can therefore prevent unnecessary downstream reviews.
|
|
246
95
|
|
|
247
|
-
|
|
96
|
+
Reviews use a fixed copy of the project by default. Records and generated output live outside the reviewed project. You can keep editing the original while a copied review runs. Reviewers inspect and judge; you or your coding tools make the changes.
|
|
248
97
|
|
|
249
|
-
|
|
98
|
+
## Choose your next step
|
|
250
99
|
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
npx ccdd run --demo --demo-dir "$CCDD_DEMO_DIR" --scenario runtime-failure --copy --critic implementation-tests --wait
|
|
258
|
-
npx ccdd run --demo --demo-dir "$CCDD_DEMO_DIR" --scenario fixed --copy --wait
|
|
259
|
-
```
|
|
100
|
+
- [Write an Artifact tool](examples/custom-text-reader/README.md) using the public tool contract.
|
|
101
|
+
- [Use default text, file, image, and desktop tools](packages/default-tools/README.md).
|
|
102
|
+
- [Review a group of materials](examples/artifact-groups/README.md), such as an effect description and its preview image.
|
|
103
|
+
- [Use Agent and Human reviewers](docs/reviewers.md), including credentials and result submission.
|
|
104
|
+
- [Explore the demo](docs/demo.md): Why → Spec → Tests → Implementation.
|
|
105
|
+
- [Look up commands, reuse rules, and exit codes](docs/project-validation.md).
|
|
260
106
|
|
|
261
|
-
|
|
107
|
+
An optional local monitor shows current-input checks and saved reviews. Start it with `npx ccdd-project monitor`.
|
|
262
108
|
|
|
263
|
-
|
|
109
|
+
## Packages and development
|
|
264
110
|
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
시연 주제는 중요한 미완료 작업을 우선 제안하는 함수입니다. 목적 변경, 구현 불일치, 수정 완료를 실제 Agent 판정과 Node 테스트로 확인합니다. 기본 도구는 TS config에 명시적으로 등록되며 Human 도구는 데스크톱 열기로 구성됩니다. 기본 시나리오의 Critic은 Agent 2개·Runtime 1개입니다.
|
|
271
|
-
|
|
272
|
-
## 로컬 모니터
|
|
273
|
-
|
|
274
|
-
```sh
|
|
275
|
-
ccdd monitor
|
|
276
|
-
# 소스에서 실행: node dist/src/cli.js monitor
|
|
277
|
-
```
|
|
278
|
-
|
|
279
|
-
표시되는 로컬 주소를 브라우저에서 열면 됩니다. 기본 주소는 `http://127.0.0.1:4318`입니다. `--port`로 변경할 수 있습니다.
|
|
280
|
-
|
|
281
|
-
프로젝트를 선택하면 **요청·진행 중·성공·실패** 네 영역에 리뷰 카드가 나타납니다. 각 영역에서 이전 요청을 추가로 불러올 수 있어 최근 완료 기록이 많아도 대기 중인 리뷰가 가려지지 않습니다. 카드를 열면 판정·근거·진행 기록과 요청에 제공된 Artifact를 확인할 수 있습니다.
|
|
282
|
-
|
|
283
|
-
```sh
|
|
284
|
-
ccdd monitor --repo /path/to/project
|
|
285
|
-
ccdd monitor --state-dir /outside/repo/state
|
|
286
|
-
```
|
|
287
|
-
|
|
288
|
-
별도 저장 위치는 `--state-dir`로 연결합니다. Human 카드는 담당 전에는 요청 영역에, claim 후에는 진행 중 영역에 표시합니다. 상세에서 등록된 Human 도구를 실행하고 GREEN·RED를 제출합니다. 후속 리뷰는 독립된 작업자로 재개되므로 모니터를 종료해도 계속 진행됩니다. 화면 조회만으로 저장된 상태나 판정을 변경하지 않습니다.
|
|
289
|
-
|
|
290
|
-
Graph의 그룹 노드는 자신의 판정과 구성원 수를 표시하며, 선택하면 멤버별 판정을 확인하고 해당 노드로 이동할 수 있습니다. 구성 관계는 Critic 의존 간선과 구분합니다. 모니터는 저장된 그룹 정보를 검증해 표시하고 설정 코드를 실행하지 않습니다.
|
|
291
|
-
|
|
292
|
-
목록의 경과 시간은 접수 이후입니다. 기존 기록에는 입력 복사·검증 이전의 시간이 없으므로 해당 준비 시간은 포함하지 않습니다. Human의 담당 이후 시간은 실제 작업 시간이 아닌 담당 후 경과입니다.
|
|
293
|
-
|
|
294
|
-
## 검증
|
|
295
|
-
|
|
296
|
-
```sh
|
|
297
|
-
npm run typecheck
|
|
298
|
-
npm test
|
|
299
|
-
```
|
|
111
|
+
| Package | Purpose |
|
|
112
|
+
| --- | --- |
|
|
113
|
+
| `@ccdd/core` | Define Artifacts, Critics, and tools. |
|
|
114
|
+
| `@ccdd/project` | Run the CLI, manage reviews, and view their history. |
|
|
115
|
+
| `@ccdd/default-tools` | Optional ready-made Artifact tools. |
|
|
300
116
|
|
|
301
|
-
|
|
117
|
+
The repository, examples, CLI, monitor, and built-in review instructions use English. See [Contributing](CONTRIBUTING.md) for setup and checks, [the context map](CONTEXT-MAP.md) for architecture, and [release instructions](docs/releases.md) for packaging and publication.
|
|
@@ -1,16 +1,16 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Default image tool and Artifact groups
|
|
2
2
|
|
|
3
|
-
`effect`
|
|
3
|
+
The `effect` document and `preview` image are independent Artifacts. `explosion` is a group referencing both IDs, with no path or type. Tools for the document and image are explicitly registered. This example is a static sample, not an actual VFX asset.
|
|
4
4
|
|
|
5
|
-
- `preview-review`:
|
|
6
|
-
- `explosion-review`:
|
|
7
|
-
- `explosion-human`:
|
|
5
|
+
- `preview-review`: Evaluates one image. Only `view_image_preview` is supplied.
|
|
6
|
+
- `explosion-review`: Evaluates the group. `read_effect` and `view_image_preview` are supplied. Tools are not duplicated when `preview` is both a member and a dependency.
|
|
7
|
+
- `explosion-human`: Opens the group's document and image in desktop applications, then accepts a submitted verdict.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
In a full Run, both group Critics must wait for the image review to pass because of explicit `deps: ['preview']`. Membership alone does not require prior evaluation. Once both group Critics are GREEN, `explosion` is GREEN while `effect` remains unreviewed.
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## Running the example
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
Install the three v2.0.2 packages on Node 24 or later. The following command works after npm publication; before that, use the local source build below. Start in the CCDD source repository and copy the example into a new project outside it.
|
|
14
14
|
|
|
15
15
|
```sh
|
|
16
16
|
CCDD_EXAMPLE_ROOT=$(mktemp -d /tmp/ccdd-groups.XXXXXX)
|
|
@@ -18,42 +18,35 @@ cp -R examples/artifact-groups "$CCDD_EXAMPLE_ROOT/project"
|
|
|
18
18
|
cd "$CCDD_EXAMPLE_ROOT/project"
|
|
19
19
|
npm init -y
|
|
20
20
|
npm pkg set type=module
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
(cd vendor/ccdd && shasum -a 256 -c SHA256SUMS)
|
|
25
|
-
npm install --ignore-scripts \
|
|
26
|
-
./vendor/ccdd/ccdd-core-2.0.1.tgz \
|
|
27
|
-
./vendor/ccdd/ccdd-project-2.0.1.tgz \
|
|
28
|
-
./vendor/ccdd/ccdd-default-tools-2.0.1.tgz
|
|
29
|
-
|
|
30
|
-
# Provider 호출 없이 그룹 구성원의 도구 준비 상태를 확인합니다.
|
|
21
|
+
npm install --ignore-scripts @ccdd/core@2.0.2 @ccdd/project@2.0.2 @ccdd/default-tools@2.0.2
|
|
22
|
+
|
|
23
|
+
# Check group member tool readiness without calling a Provider.
|
|
31
24
|
npx ccdd tools check --artifact explosion --for agent
|
|
32
|
-
#
|
|
25
|
+
# Select an individual Artifact for actual image reading.
|
|
33
26
|
npx ccdd tools check --artifact preview --for agent --tool view_image --execute
|
|
34
27
|
|
|
35
|
-
#
|
|
28
|
+
# Review one Critic; this legacy command skips waiting for prerequisite verdicts.
|
|
36
29
|
npx ccdd run --copy --critic explosion-review --codex-auth-file "$HOME/.codex/auth.json" --wait
|
|
37
30
|
```
|
|
38
31
|
|
|
39
|
-
|
|
32
|
+
Actual Agent review requires authentication and access to a model supporting image input. See the [reviewer guide](../../docs/reviewers.md) for authentication methods. Tool checks do not call a model. The `--execute` output above includes actual image blocks in base64.
|
|
40
33
|
|
|
41
|
-
|
|
34
|
+
If core is already installed, change the first `cp` source to `node_modules/@ccdd/core/examples/artifact-groups`.
|
|
42
35
|
|
|
43
|
-
|
|
36
|
+
Start a full Run with Human review by registering a local notification:
|
|
44
37
|
|
|
45
38
|
```sh
|
|
46
39
|
npx ccdd run --copy --human-inbox --codex-auth-file "$HOME/.codex/auth.json"
|
|
47
40
|
npx ccdd monitor
|
|
48
41
|
```
|
|
49
42
|
|
|
50
|
-
|
|
43
|
+
Select a project and Run in the monitor, then click the group node in Graph to inspect its members. Claim the Human request, click `{explosion}`, execute each member's `open` tool, and submit a verdict with evidence. Default desktop opening targets macOS; explicitly register an executable on other operating systems.
|
|
51
44
|
|
|
52
|
-
`view_image
|
|
45
|
+
`view_image` reuses Pi `read` image results. It detects PNG/JPEG/WebP from file content, with a 4MiB limit. GIF, BMP, animated PNG, and text results fail; no automatic conversion or resizing occurs. When registered on a directory Artifact, pass an internal path such as `{"path":"frames/preview.png"}`.
|
|
53
46
|
|
|
54
|
-
##
|
|
47
|
+
## Using a local source build
|
|
55
48
|
|
|
56
|
-
|
|
49
|
+
To test modified source, prepare three tarballs in the CCDD repository:
|
|
57
50
|
|
|
58
51
|
```sh
|
|
59
52
|
npm ci
|
|
@@ -64,4 +57,4 @@ npm pack --ignore-scripts --workspace @ccdd/project --pack-destination "$CCDD_LO
|
|
|
64
57
|
npm pack --ignore-scripts --workspace @ccdd/default-tools --pack-destination "$CCDD_LOCAL_PACKAGES"
|
|
65
58
|
```
|
|
66
59
|
|
|
67
|
-
|
|
60
|
+
In the same shell, create the new example project from the steps above, then replace the npm version installation with `npm install --ignore-scripts "$CCDD_LOCAL_PACKAGES"/*.tgz`. Subsequent tool checks and review commands are the same. To also run the full test suite and separate installation checks on source fixed to a commit, use `--dry-run` with the [local Release command](../../docs/releases.md#releasing-a-specific-commit-locally).
|
|
@@ -19,19 +19,19 @@ export default defineConfig({
|
|
|
19
19
|
},
|
|
20
20
|
critics: [
|
|
21
21
|
{
|
|
22
|
-
id: 'preview-review', title: '
|
|
22
|
+
id: 'preview-review', title: 'Image visibility', target: 'preview', deps: [],
|
|
23
23
|
profile: { kind: 'agent', provider: 'openai-codex', model: 'gpt-6-astra', reasoning: 'medium' },
|
|
24
|
-
payload: { instruction: '{preview}
|
|
24
|
+
payload: { instruction: 'Check whether {preview} has a bright center and an orange ring distinguishable from the dark background. Review the image itself; matching the effect specification is outside this review.' },
|
|
25
25
|
},
|
|
26
26
|
{
|
|
27
|
-
id: 'explosion-review', title: '
|
|
27
|
+
id: 'explosion-review', title: 'Match the effect description and preview', target: 'explosion', deps: ['preview'],
|
|
28
28
|
profile: { kind: 'agent', provider: 'openai-codex', model: 'gpt-6-astra', reasoning: 'medium' },
|
|
29
|
-
payload: { instruction: '{explosion}
|
|
29
|
+
payload: { instruction: 'Observe every member of {explosion} and evaluate whether {preview} matches the static appearance specified in {effect}. Animation timing and actual VFX runtime behavior are outside the scope of this static example.' },
|
|
30
30
|
},
|
|
31
31
|
{
|
|
32
|
-
id: 'explosion-human', title: '
|
|
32
|
+
id: 'explosion-human', title: 'Review the group on the desktop', target: 'explosion', deps: ['preview'],
|
|
33
33
|
profile: { kind: 'human' },
|
|
34
|
-
payload: { instruction: '{explosion}
|
|
34
|
+
payload: { instruction: 'Open the document and image in {explosion} with their desktop programs, compare them, and submit your verdict.' },
|
|
35
35
|
},
|
|
36
36
|
],
|
|
37
37
|
});
|
|
@@ -1,12 +1,12 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Static explosion preview
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
This example groups an effect description and a static PNG in place of actual VFX files.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Appearance to review:
|
|
6
6
|
|
|
7
|
-
-
|
|
8
|
-
-
|
|
9
|
-
-
|
|
10
|
-
-
|
|
7
|
+
- A circular effect is centered on a dark navy background.
|
|
8
|
+
- The center is a bright cream circle.
|
|
9
|
+
- An orange circular ring surrounds the center, separated by a gap.
|
|
10
|
+
- There is no text or UI button.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
This static example does not verify animation speed, lifetime, or execution in a game engine.
|
|
@@ -1,25 +1,25 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Custom Reader
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
This example directly registers `{ metadata, execute }` without the default tool library. `customTextReader()` creates a definition; actual file reading occurs when an Agent calls `read_spec` or `read_why`.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Each project must include its own dependencies. Copy this folder into a new project outside the repository, then install core and Project. The commands below work after npm v2.0.2 publication; before that, use the local tarballs described below. The example is included in the source repository and the core package's `examples/custom-text-reader`. It does not rely on CCDD installed in a parent repository.
|
|
6
6
|
|
|
7
7
|
```sh
|
|
8
|
-
#
|
|
8
|
+
# Copy the example from the CCDD source repository.
|
|
9
9
|
cp -R examples/custom-text-reader /tmp/ccdd-custom-reader
|
|
10
10
|
cd /tmp/ccdd-custom-reader
|
|
11
11
|
npm init -y
|
|
12
12
|
npm pkg set type=module
|
|
13
|
-
npm install --ignore-scripts @ccdd/core@2.0.
|
|
13
|
+
npm install --ignore-scripts @ccdd/core@2.0.2 @ccdd/project@2.0.2
|
|
14
14
|
npx ccdd tools check --artifact spec --for agent --tool read
|
|
15
15
|
npx ccdd tools check --artifact spec --for agent --tool read --execute --args '{"startLine":1,"lineCount":20}'
|
|
16
16
|
npx ccdd run --copy --critic spec-why --codex-auth-file "$HOME/.codex/auth.json" --wait
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
This example installs core and Project without the default tool library. Alternatively, in the source repository run `npm run release:npm -- --commit <40-character SHA> --dry-run` to verify and generate matching `ccdd-core-2.0.2.tgz` and `ccdd-project-2.0.2.tgz` files, then install with `npm install --ignore-scripts <core.tgz> <project.tgz>`. This local verification requires no GitHub authentication. If CCDD is already installed, change the first `cp` source to `node_modules/@ccdd/core/examples/custom-text-reader`.
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
The tool omits `preflight`. The default check distinguishes confirmed registration from unverified execution; `--execute` actually reads the file. Agent review requires valid Provider authentication.
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
This Reader is a small implementation illustrating the structure. It reads the file into memory before checking the 1MiB limit and limits returned text to 64KiB. A streaming reader is more appropriate for large files. It preserves UTF-8, CRLF, and the final newline, and distinguishes an empty file from a read past EOF. It returns an observation receipt only when actual content or an empty file was observed.
|
|
24
24
|
|
|
25
|
-
Human
|
|
25
|
+
There is no Human duplicate of the Agent Reader. This type has no Human tools, so a Human Critic cannot use it. To add human viewing, write a custom tool that opens a desktop application or explicitly register `human.desktop.open()` from `@ccdd/default-tools`.
|
|
@@ -5,7 +5,7 @@ import { defineConfig, defineTool } from '@ccdd/core';
|
|
|
5
5
|
function customTextReader() {
|
|
6
6
|
return defineTool({
|
|
7
7
|
metadata: {
|
|
8
|
-
description: '
|
|
8
|
+
description: 'Read the specified line range from {artifactName}.',
|
|
9
9
|
inputSchema: {
|
|
10
10
|
type: 'object',
|
|
11
11
|
properties: {
|
|
@@ -57,8 +57,8 @@ export default defineConfig(() => ({
|
|
|
57
57
|
spec: { type: 'document', path: 'spec.md' },
|
|
58
58
|
},
|
|
59
59
|
critics: [{
|
|
60
|
-
id: 'spec-why', title: 'Spec
|
|
60
|
+
id: 'spec-why', title: 'Does Spec match Why?', target: 'spec', deps: ['why'],
|
|
61
61
|
profile: { kind: 'agent', provider: 'openai-codex', model: 'gpt-6-astra', reasoning: 'medium' },
|
|
62
|
-
payload: { instruction: '
|
|
62
|
+
payload: { instruction: 'Read both documents and evaluate whether Spec satisfies the maximum task count in Why.' },
|
|
63
63
|
}],
|
|
64
64
|
}));
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ccdd/core",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.2",
|
|
4
4
|
"publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
|
|
5
5
|
"repository": { "type": "git", "url": "git+https://github.com/lhj6102/ccdd.git" },
|
|
6
6
|
"description": "Artifact, Critic, relationship and tool definitions for CCDD",
|
|
@@ -19,7 +19,8 @@
|
|
|
19
19
|
"build:ui": "npm run typecheck:ui && vite build --config vite.config.ts",
|
|
20
20
|
"typecheck:ui": "node src/monitor/ui/typecheck.cjs -p tsconfig.ui.json --noEmit",
|
|
21
21
|
"typecheck": "node node_modules/typescript/bin/tsc -p tsconfig.json --noEmit && npm run typecheck:ui",
|
|
22
|
-
"
|
|
22
|
+
"check:language": "node scripts/check-language.mjs",
|
|
23
|
+
"test": "npm run check:language && npm run build && node --test dist/test/*.test.js",
|
|
23
24
|
"test:packages": "npm run build && node scripts/smoke-project.mjs",
|
|
24
25
|
"prepack": "npm run build",
|
|
25
26
|
"release": "node scripts/local-release.mjs",
|